docs(algo): 采样环缓冲补「为什么需要/设计思想」两节与两张配图

- 采集与算法层设计说明第 5 节由单段说明拆成 5.1~5.5:为什么需要这一层
  (三个缺口 + 两个被否决的替代方案)、设计思想(五条不变量)、环内布局
  与 start 推导、API 契约、要点与禁令。
- 新增两张配图(生成器 + 产物同批提交):
  采样环缓冲_为什么需要.svg —— 上游 1 kHz 覆盖写只交最新一帧 vs 下游
  20 点滑窗,缺口 19 点,以及三个消费者必须同源;
  采样环缓冲_环形布局.svg —— 40 格环里哪 20 格是本窗、写指针指「下一格」、
  回绕方向与三条设计不变量。
- 5.5 补一条「读者与写者必须同任务」,与故障录波设计说明的取窗竞态口径一致。
- 门禁:doc-links --sections-strict 通过(28 处章节引用全部可判定);
  id-check 新增行无未登记编号;generated-fresh 21 个生成器 16 一致、0 新漂移。
This commit is contained in:
2026-10-29 17:15:48 +08:00
parent de512a0db8
commit c377fc8c15
6 changed files with 788 additions and 4 deletions
@@ -0,0 +1,56 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1060" height="600" viewBox="0 0 1060 600" font-family="Microsoft YaHei, Segoe UI, PingFang SC, sans-serif">
<rect x="0" y="0" width="1060" height="600" fill="#ffffff"/>
<text x="46.0" y="42.0" font-size="21" font-weight="700" fill="#0f172a">上游只交最新一帧,相量却要一整周波 —— 采样环补的就是这 19 点</text>
<text x="46.0" y="68.0" font-size="13" fill="#64748b">上游(adc_input)每 1 ms 交付一次,且只交本拍;旧值被覆盖、不保留历史。下游相量要的是「以当前时刻为终止的 20 点滑窗」。</text>
<text x="46.0" y="88.0" font-size="13" fill="#64748b">本层不改采集、不改算法,只把「覆盖写的最新值」转成「可回溯的滑动窗」——三个消费者共用同一份。</text>
<rect x="34.0" y="112.0" width="992.0" height="188.0" rx="12" fill="#fff1f2"/>
<text x="46.0" y="136.0" font-size="14.5" font-weight="700" fill="#e11d48">① 上游交付物:1 kHz 覆盖写,每拍只交一帧</text>
<text x="46.0" y="156.0" font-size="11" fill="#64748b">20 个刻度 = 一周波 20 点(1 kHz @ 50 Hz);上游只把最后一个点交出来</text>
<line x1="62.0" y1="236.0" x2="806.0" y2="236.0" stroke="#334155" stroke-width="2"/>
<line x1="74.0" y1="236.0" x2="74.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="112.0" y1="236.0" x2="112.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="150.0" y1="236.0" x2="150.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="188.0" y1="236.0" x2="188.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="226.0" y1="236.0" x2="226.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="264.0" y1="236.0" x2="264.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="302.0" y1="236.0" x2="302.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="340.0" y1="236.0" x2="340.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="378.0" y1="236.0" x2="378.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="416.0" y1="236.0" x2="416.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="454.0" y1="236.0" x2="454.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="492.0" y1="236.0" x2="492.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="530.0" y1="236.0" x2="530.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="568.0" y1="236.0" x2="568.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="606.0" y1="236.0" x2="606.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="644.0" y1="236.0" x2="644.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="682.0" y1="236.0" x2="682.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="720.0" y1="236.0" x2="720.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="758.0" y1="236.0" x2="758.0" y2="214.0" stroke="#94a3b8" stroke-width="1.4"/>
<line x1="796.0" y1="236.0" x2="796.0" y2="214.0" stroke="#2563eb" stroke-width="2"/>
<rect x="65.0" y="192.0" width="740.0" height="20.0" rx="6" fill="none" stroke="#e11d48" stroke-width="1.8" stroke-dasharray="7 5"/>
<text x="435.0" y="207.0" font-size="11.5" text-anchor="middle" font-weight="700" fill="#e11d48">相量要的 20 点窗(一整周波)</text>
<circle cx="796.0" cy="236.0" r="5.5" fill="#2563eb"/>
<text x="808.0" y="241.0" font-size="11" font-weight="700" fill="#2563eb">最新一帧(本拍)</text>
<rect x="65.0" y="244.0" width="702.0" height="5.0" rx="2.5" fill="#e11d48"/>
<text x="74.0" y="266.0" font-size="11" text-anchor="middle" fill="#64748b">k−19</text>
<text x="454.0" y="266.0" font-size="11" text-anchor="middle" fill="#64748b">k−9</text>
<text x="796.0" y="266.0" font-size="11" text-anchor="middle" fill="#64748b">k</text>
<text x="46.0" y="288.0" font-size="11" font-weight="700" fill="#e11d48">这 19 个点上游不保留 —— 不缓冲就永远取不到</text>
<text x="46.0" y="334.0" font-size="14.5" font-weight="700" fill="#2563eb">② 下游需求:三个消费者,必须看同一份历史</text>
<text x="46.0" y="354.0" font-size="11" fill="#64748b">共用同一份环 = 同一拍只有一个窗 —— 口径不会各自漂移</text>
<rect x="46.0" y="370.0" width="300.0" height="112.0" rx="8" fill="#eff6ff" stroke="#2563eb" stroke-width="1.8"/>
<text x="58.0" y="394.0" font-size="13.5" font-weight="700" fill="#0f172a">phasor_run()</text>
<text x="58.0" y="416.0" font-size="11.5" fill="#64748b">每 1 ms 要一整周波 20 点,算全周傅氏相量(幅值</text>
<text x="58.0" y="431.0" font-size="11.5" fill="#64748b"> / 相位)。窗短一点就不是「全周」,谐波抑制立刻</text>
<text x="58.0" y="446.0" font-size="11.5" fill="#64748b">失效。</text>
<rect x="365.0" y="370.0" width="300.0" height="112.0" rx="8" fill="#f0fdf4" stroke="#16a34a" stroke-width="1.8"/>
<text x="377.0" y="394.0" font-size="13.5" font-weight="700" fill="#0f172a">freq_run()</text>
<text x="377.0" y="416.0" font-size="11.5" fill="#64748b">要相邻两拍相量的相位差 → 反推频率。它与相量必须</text>
<text x="377.0" y="431.0" font-size="11.5" fill="#64748b">落在同一个窗上,否则相位差里混进窗长误差。</text>
<rect x="684.0" y="370.0" width="300.0" height="112.0" rx="8" fill="#fffbeb" stroke="#d97706" stroke-width="1.8"/>
<text x="696.0" y="394.0" font-size="13.5" font-weight="700" fill="#0f172a">meas_tick()</text>
<text x="696.0" y="416.0" font-size="11.5" fill="#64748b">每 200 ms 发布遥测快照。快照里的相量 / 频率 /</text>
<text x="696.0" y="431.0" font-size="11.5" fill="#64748b"> 品质位都取自同一次窗,不允许各取各的。</text>
<line x1="46.0" y1="516.0" x2="1014.0" y2="516.0" stroke="#cbd5e1" stroke-width="1"/>
<text x="46.0" y="540.0" font-size="13" fill="#64748b">缓冲只解决「取得到历史」,不解决「这些点是否同刻」:同刻性归上游 adc_input 负责,本层只按时序存 / 取,不做任何跨通道运算。</text>
</svg>

After

Width:  |  Height:  |  Size: 5.9 KiB

@@ -0,0 +1,115 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1060" height="580" viewBox="0 0 1060 580" font-family="Microsoft YaHei, Segoe UI, PingFang SC, sans-serif">
<rect x="0" y="0" width="1060" height="580" fill="#ffffff"/>
<text x="46.0" y="42.0" font-size="21" font-weight="700" fill="#0f172a">40 格环:写指针指「下一格」,窗永远紧贴它身后</text>
<text x="46.0" y="68.0" font-size="13" fill="#64748b">DEPTH = 2 周波 × 20 点 = 40;窗长 n 取 1~40,取的是 [head−n, head−1] 这 n 格。</text>
<text x="46.0" y="88.0" font-size="13" fill="#64748b">图例:蓝 = 本窗 20 点,灰 = 更旧的 10 点,琥珀 = 最旧的 10 点(下一批被覆盖)。</text>
<text x="46.0" y="108.0" font-size="13" fill="#64748b">窗首 start = (head + 40 − n) % 40 —— 先加 40 再减,减法就不落到负数;每写一格整窗右移一格。</text>
<rect x="46.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#f1f5f9" stroke="#94a3b8" stroke-width="1.2"/>
<text x="57.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">0</text>
<rect x="70.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#f1f5f9" stroke="#94a3b8" stroke-width="1.2"/>
<text x="81.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">1</text>
<rect x="94.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#f1f5f9" stroke="#94a3b8" stroke-width="1.2"/>
<text x="105.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">2</text>
<rect x="118.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#f1f5f9" stroke="#94a3b8" stroke-width="1.2"/>
<text x="129.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">3</text>
<rect x="142.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#f1f5f9" stroke="#94a3b8" stroke-width="1.2"/>
<text x="153.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">4</text>
<rect x="166.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#f1f5f9" stroke="#94a3b8" stroke-width="1.2"/>
<text x="177.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">5</text>
<rect x="190.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#f1f5f9" stroke="#94a3b8" stroke-width="1.2"/>
<text x="201.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">6</text>
<rect x="214.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#f1f5f9" stroke="#94a3b8" stroke-width="1.2"/>
<text x="225.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">7</text>
<rect x="238.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#f1f5f9" stroke="#94a3b8" stroke-width="1.2"/>
<text x="249.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">8</text>
<rect x="262.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#f1f5f9" stroke="#94a3b8" stroke-width="1.2"/>
<text x="273.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">9</text>
<rect x="286.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="297.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">10</text>
<rect x="310.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="321.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">11</text>
<rect x="334.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="345.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">12</text>
<rect x="358.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="369.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">13</text>
<rect x="382.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="393.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">14</text>
<rect x="406.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="417.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">15</text>
<rect x="430.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="441.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">16</text>
<rect x="454.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="465.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">17</text>
<rect x="478.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="489.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">18</text>
<rect x="502.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="513.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">19</text>
<rect x="526.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="537.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">20</text>
<rect x="550.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="561.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">21</text>
<rect x="574.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="585.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">22</text>
<rect x="598.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="609.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">23</text>
<rect x="622.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="633.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">24</text>
<rect x="646.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="657.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">25</text>
<rect x="670.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="681.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">26</text>
<rect x="694.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="705.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">27</text>
<rect x="718.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="729.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">28</text>
<rect x="742.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#eff6ff" stroke="#2563eb" stroke-width="2"/>
<text x="753.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">29</text>
<rect x="766.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#fffbeb" stroke="#d97706" stroke-width="1.4"/>
<text x="777.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">30</text>
<rect x="790.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#fffbeb" stroke="#d97706" stroke-width="1.4"/>
<text x="801.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">31</text>
<rect x="814.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#fffbeb" stroke="#d97706" stroke-width="1.4"/>
<text x="825.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">32</text>
<rect x="838.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#fffbeb" stroke="#d97706" stroke-width="1.4"/>
<text x="849.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">33</text>
<rect x="862.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#fffbeb" stroke="#d97706" stroke-width="1.4"/>
<text x="873.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">34</text>
<rect x="886.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#fffbeb" stroke="#d97706" stroke-width="1.4"/>
<text x="897.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">35</text>
<rect x="910.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#fffbeb" stroke="#d97706" stroke-width="1.4"/>
<text x="921.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">36</text>
<rect x="934.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#fffbeb" stroke="#d97706" stroke-width="1.4"/>
<text x="945.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">37</text>
<rect x="958.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#fffbeb" stroke="#d97706" stroke-width="1.4"/>
<text x="969.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">38</text>
<rect x="982.0" y="200.0" width="22.0" height="54.0" rx="3" fill="#fffbeb" stroke="#d97706" stroke-width="1.4"/>
<text x="993.0" y="230.5" font-size="9" text-anchor="middle" fill="#64748b">39</text>
<line x1="297.0" y1="184.0" x2="297.0" y2="198.0" stroke="#2563eb" stroke-width="1.4"/>
<polygon points="297.0,200.0 292.5,192.0 301.5,192.0" fill="#2563eb"/>
<text x="297.0" y="176.0" font-size="11" text-anchor="start" font-weight="700" fill="#2563eb">start(最老点)</text>
<line x1="753.0" y1="184.0" x2="753.0" y2="198.0" stroke="#2563eb" stroke-width="1.4"/>
<polygon points="753.0,200.0 748.5,192.0 757.5,192.0" fill="#2563eb"/>
<text x="753.0" y="176.0" font-size="11" text-anchor="end" font-weight="700" fill="#2563eb">head−1(最新点)</text>
<line x1="777.0" y1="184.0" x2="777.0" y2="198.0" stroke="#d97706" stroke-width="1.4"/>
<polygon points="777.0,200.0 772.5,192.0 781.5,192.0" fill="#d97706"/>
<text x="777.0" y="176.0" font-size="11" text-anchor="start" font-weight="700" fill="#d97706">head(下一拍写这里)</text>
<line x1="993.0" y1="286.0" x2="65.0" y2="286.0" stroke="#e11d48" stroke-width="1.6" stroke-dasharray="7 5"/>
<polygon points="57.0,286.0 66.0,281.5 66.0,290.5" fill="#e11d48"/>
<text x="46.0" y="308.0" font-size="11" font-weight="700" fill="#e11d48">写满后回绕:39 的下一格是 0 —— 窗可能跨过环尾,所以取数必须逐点取模</text>
<rect x="46.0" y="340.0" width="300.0" height="120.0" rx="8" fill="#f0fdf4" stroke="#16a34a" stroke-width="1.8"/>
<text x="58.0" y="364.0" font-size="13.5" font-weight="700" fill="#0f172a">整帧写完才推进 head</text>
<text x="58.0" y="386.0" font-size="11.5" fill="#64748b">9 路语义值一次写齐、再动指针。单帧内不存在「半</text>
<text x="58.0" y="401.0" font-size="11.5" fill="#64748b">新半旧」,消费侧取到的窗永远落在整帧边界上。</text>
<rect x="365.0" y="340.0" width="300.0" height="120.0" rx="8" fill="#eff6ff" stroke="#2563eb" stroke-width="1.8"/>
<text x="377.0" y="364.0" font-size="13.5" font-weight="700" fill="#0f172a">只存不算是分层契约</text>
<text x="377.0" y="386.0" font-size="11.5" fill="#64748b">同刻性归上游 adc_input 负责;本层不假设、不校</text>
<text x="377.0" y="401.0" font-size="11.5" fill="#64748b">正,也不做任何跨通道运算——所以它能脱离硬件做主</text>
<text x="377.0" y="416.0" font-size="11.5" fill="#64748b">机侧单测。</text>
<rect x="684.0" y="340.0" width="300.0" height="120.0" rx="8" fill="#fffbeb" stroke="#d97706" stroke-width="1.8"/>
<text x="696.0" y="364.0" font-size="13.5" font-weight="700" fill="#0f172a">容量取 2 周波</text>
<text x="696.0" y="386.0" font-size="11.5" fill="#64748b">1 周波就够算全周傅氏;另 1 周波是给 1.5~2 周波</text>
<text x="696.0" y="401.0" font-size="11.5" fill="#64748b">长窗(抗衰减直流)留的余量,改容量只动一个宏。</text>
<line x1="46.0" y1="490.0" x2="1014.0" y2="490.0" stroke="#cbd5e1" stroke-width="1"/>
<text x="46.0" y="514.0" font-size="13" fill="#64748b">n = 40 时 start == head:环满时「下一拍要覆盖的那一格」恰好就是最老点 —— 不是特例,是唯一自洽解。同理 n = 20 时窗正好是 head 身后的 20 格,不</text>
<text x="46.0" y="533.0" font-size="13" fill="#64748b">多不少。</text>
</svg>

After

Width:  |  Height:  |  Size: 12 KiB