0f7b5a87fb
登记簿、文档与代码注释里的存量字母加数字编号(N-x / S-x / T-x / E-x / A-x / 卡号) 一律改写为语义短语,净删 2,028 处引用;删除基线与待确认、并行分道方案、排期详述、 采集保护收尾 4 篇(内容已并入 docs/任务规划/README 与登记簿)。 门禁机器与三张账同批重打:check_ids.py 新增变更记录行豁免与第二根护栏 undecidable_total_ceiling;check_test_traceability.py 只加 stdout/stderr UTF-8 reconfigure(TC_RE 未动);check_cubemx_survival.py 的 --write 固定 newline=LF; id_registry / id_aliases(+19 条 retired-to-phrase)/ id_known_backlog 重打。 test/ 56 个文件同步 TC 标签语义化,其中 18 个 TU 改了 CHECK / printf 里的标签文字, 是本批唯一改变构建产物的文件集合。 为什么合成一笔、不拆四笔(实测撞闸,非偏好):pre-commit 跑钩子前会 stash 未 staged 部分,拆开后中间提交必然是「新规则 + 旧语料」——实跑可判定 85.15% < 基线 86.00%、 不可判定 1,453 > 上限 1,166,编号门禁直接拦下。编号识别面与它描述的语料只能同码移动。 实跑基线(工作区全量):754 文件 / 8,230 处编号字面量 / 可判定 7,079 = 86.01% (基线 86.0%,容差 0.1pp)/ 不可判定绝对数 1,151(上限 1,166)/ 校验 1-6 错误级 0 / 告警 = 悬空 2(App/algo/freq.c 的 S2,属 §4.4 同号不同义)+ 孤儿 50。 基线从 84.0 抬到 86.0 的理由见 docs/门禁说明/id-check.md §7.6:本批真删了 2,028 处 引用,可判定面随真实内容上升,不是把分母做小。同批新增排除 docs/硬件平台/ 语料,使 识别面少 264 处——芯片手册位号与网表料号不属编号空间(registry 有 excluded_paths_note)。 ⚠ 余量只剩 0.11pp(约 10 处)与绝对数 15 处:把「可判定的引用」改成散文会立刻撞第二 根护栏。另遗留一项:id_aliases 里 retired 的 N / S / T / A 别名没有 scope(U1~U5 有), 今后有人新写一个 A-4,校验 3 不会响,只能靠人,建议下批补 scope。 固件不变证据:115 个 .c/.h 剥注释并归一字符串后与 HEAD 逐字节全等,残留代码差异 0; App / Src / Drivers 的字符串字面量零改动。@build 0 错误 0 警告;40/40 主机套件、2,889 断言全通过;覆盖率 line 89.2% / func 92.6%;pre-commit 48 钩子 --all-files 全绿; check_doc_links --all 通过(176 文档,章节引用无法判定 0);逐字节卫生核过:14 个带 BOM 文件与 HEAD 一致、0 个 CR、0 个 U+FFFD,字符串字面量纯 ASCII。 .cubemx_survival_baseline.json 的 watchdog-module 哈希 56bf27 变 2bb051 属合法: Src/freertos.c 的 USER CODE 区内只有注释文字随编号改写,代码未变。 同批带上体积同码凭证与 RAM 台账行(@build 之后盖戳):RW_IRAM1 79,008 B / 60.3%, RW_CCM 57,376 B / 87.9%,阈值 92%。
257 lines
11 KiB
Python
257 lines
11 KiB
Python
#!/usr/bin/env python3
|
||
# -*- coding: utf-8 -*-
|
||
"""生成 docs/images/采样有效性校验数据流.svg —— L1-6「观测计数 → 快照 → 判定 → 位图 → 消费者」(纯标准库)。
|
||
|
||
为什么不用 Mermaid:本图要表达**三条量车道(TPAFE / STM32 / 时基)平行流过五个阶段**,
|
||
Mermaid 自动布局会把三条车道挤成交叉线、也保不住"同一拍取数"的横向对齐。
|
||
这里按车道手工排布:每车道一行,箭头全部水平,行内可直接横向读一遍判据。
|
||
|
||
用法(仓库根目录,任意 python3):
|
||
python tools/arch_diagram/gen_adc_health_flow_svg.py
|
||
输出:
|
||
docs/images/采样有效性校验数据流.svg
|
||
改内容时:只编辑本文件顶部的 STAGES / LANES 数据后重跑。
|
||
"""
|
||
import html
|
||
import os
|
||
import xml.etree.ElementTree as ET
|
||
|
||
ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
|
||
OUT = os.path.join(ROOT, "docs", "images", "采样有效性校验数据流.svg")
|
||
|
||
# ----------------------------- 画布与尺寸 -----------------------------
|
||
W = 1580
|
||
PAD = 40
|
||
TITLE_FONT = 21
|
||
SUB_FONT = 13
|
||
HEAD_FONT = 13
|
||
CELL_TITLE_FONT = 12.5
|
||
CELL_NOTE_FONT = 11
|
||
LANE_FONT = 12
|
||
FOOT_FONT = 12
|
||
|
||
CELL_H = 148
|
||
LANE_GAP = 34
|
||
MAIN_Y = 214
|
||
LANE_LABEL_W = 96
|
||
COLS = [
|
||
(PAD + LANE_LABEL_W, 268), # 阶段 1:观测计数(ISR / 消费侧)
|
||
(PAD + LANE_LABEL_W + 288, 236), # 阶段 2:本拍快照
|
||
(PAD + LANE_LABEL_W + 544, 276), # 阶段 3:判定(纯逻辑)
|
||
(PAD + LANE_LABEL_W + 840, 264), # 阶段 4:出口位图
|
||
(PAD + LANE_LABEL_W + 1124, 250), # 阶段 5:消费者
|
||
]
|
||
|
||
FONT = "Microsoft YaHei, Segoe UI, PingFang SC, sans-serif"
|
||
C_LANE = ["#0d9488", "#2563eb", "#7c3aed"]
|
||
BG_LANE = ["#f0fdfa", "#eff6ff", "#f5f3ff"]
|
||
C_HEAD, BG_HEAD = "#475569", "#f1f5f9"
|
||
INK, MUTED = "#0f172a", "#64748b"
|
||
|
||
# ----------------------------- 数据(改这里) -----------------------------
|
||
STAGES = [
|
||
"1. 观测计数(ISR / 驱动侧)",
|
||
"2. 本拍计数快照",
|
||
"3. 判定(adc_health.c 纯逻辑)",
|
||
"4. 出口位图(32 位)",
|
||
"5. 消费者与处置",
|
||
]
|
||
|
||
# 每条车道 = 一行;cells 与 STAGES 一一对应
|
||
LANES = [
|
||
dict(
|
||
name="TPAFE",
|
||
color=0,
|
||
cells=[
|
||
dict(title="tpafe5160.c 的 BUSY EXTI",
|
||
lines=["s_frame_seq++:每读完一帧 +1",
|
||
"s_frstdata_err++:无跳变帧累计计数",
|
||
"ISR 内只加计数,不打日志"] ),
|
||
dict(title="adcTask 每拍 poll 之后取值",
|
||
lines=["tpafe_seq",
|
||
"tpafe_frst_err(uint16 放宽)",
|
||
"⚠ 必须取本拍 poll 之后的值"] ),
|
||
dict(title="序号差值 d = seq - 上次",
|
||
lines=["d < 0 → 置倒退位并重新对齐",
|
||
"d > 1 → tgap += d-1 + 当拍事件",
|
||
"d >= 1 → 刷新「最后前进时刻」"] ),
|
||
dict(title="本车道出口",
|
||
lines=["bit0 ADC_HF_TPAFE_STALL(自愈)",
|
||
"bit2 ADC_HF_SEQ_BACKWARD(锁存)",
|
||
"bit6/bit3 ADC_HE_TPAFE_GAP / FRSTDATA"] ),
|
||
dict(title="闭锁 + 留痕 + 计数",
|
||
lines=["protectTask 每 20 ms 读 bit0/bit2",
|
||
"gap / FRSTDATA 事件 → 编排层日志",
|
||
"tgap → 10 s 心跳字段"] ),
|
||
],
|
||
),
|
||
dict(
|
||
name="STM32",
|
||
color=1,
|
||
cells=[
|
||
dict(title="adc_input.c(DMA2 Stream4)",
|
||
lines=["s_dma_seq++:半区/整区完成各一次",
|
||
"s_stm32_gaps += d-1:丢帧点数",
|
||
"s_stm32_errs++:连续 >=2 拍无新帧",
|
||
"s_stm32_hw_errs++:HAL 错误回调"] ),
|
||
dict(title="同一拍的四个 STM32 计数",
|
||
lines=["stm32_seq / stm32_errs",
|
||
"stm32_gaps / stm32_hw_errs",
|
||
"gap 细账不重复取(L1 已算)"] ),
|
||
dict(title="序号差值 d + 三处计数增量",
|
||
lines=["d < 0 → 同一个 SEQ_BACKWARD 位",
|
||
"d >= 1 → 刷新最后前进时刻",
|
||
"增量 != 0 → 事件 + 锁存"] ),
|
||
dict(title="本车道出口",
|
||
lines=["bit1 ADC_HF_STM32_STALL(自愈)",
|
||
"bit2 共用(两车道同一位)",
|
||
"bit7/bit4/bit5 GAP / ERR / HW_ERR"] ),
|
||
dict(title="闭锁 + 严重事件",
|
||
lines=["bit1/bit2 → 同左闭锁路径",
|
||
"STM32_ERR / HW_ERR:恒 0 增量",
|
||
"出现即 DBG_ERROR + 自检留痕"] ),
|
||
],
|
||
),
|
||
dict(
|
||
name="时基",
|
||
color=2,
|
||
cells=[
|
||
dict(title="osKernelGetTickCount()",
|
||
lines=["HAL 时基 TIM7,tick = 1 ms",
|
||
"2^32 ms 后自然回绕"] ),
|
||
dict(title="now_ms:本拍唯一一份",
|
||
lines=["健康判定与心跳上报共用",
|
||
"不在判定层内再取一次"] ),
|
||
dict(title="差值法 (int32_t)(now - adv)",
|
||
lines=["回绕安全(取有符号差)",
|
||
">= ADC_HEALTH_STALL_MS(100)",
|
||
"可判定窗 ±2^31 ≈ ±24.85 天"] ),
|
||
dict(title="tpafe_stall_ms",
|
||
lines=["静默期内给出停滞时长",
|
||
"正常态恒为 0",
|
||
"STM32 侧未上报(观测盲区)"] ),
|
||
dict(title="上升沿日志可读性",
|
||
lines=["health: flags=… stall_ms=…",
|
||
"回答到底停了多少毫秒"] ),
|
||
],
|
||
),
|
||
]
|
||
|
||
FOOT = ("判定层零平台依赖(只 include <stdint.h>、不碰寄存器 / 不取数 / 不打日志)→ 主机侧以 #include 原样纳入、免桩全覆盖单测。"
|
||
"详见 docs/算法/采样有效性校验设计说明.md")
|
||
|
||
|
||
# ----------------------------- 工具函数 -----------------------------
|
||
def esc(s):
|
||
return html.escape(s, quote=True)
|
||
|
||
|
||
def text_w(s, fs):
|
||
"""粗略估算文本像素宽:CJK/全角 ≈ 1.0em,其余 ≈ 0.58em(宁可偏大)。"""
|
||
return sum(fs * (1.0 if ord(ch) >= 0x2E80 else 0.58) for ch in s)
|
||
|
||
|
||
OVERFLOW = []
|
||
|
||
|
||
def check_fit(s, fs, avail, where):
|
||
if text_w(s, fs) > avail:
|
||
OVERFLOW.append("%s: %.0f > %.0f [%s]" % (where, text_w(s, fs), avail, s))
|
||
|
||
|
||
# ----------------------------- 生成 -----------------------------
|
||
def build():
|
||
out = []
|
||
add = out.append
|
||
|
||
n_cells = max(len(l["cells"]) for l in LANES)
|
||
for li, lane in enumerate(LANES):
|
||
for ci, cell in enumerate(lane["cells"]):
|
||
_, cw = COLS[ci]
|
||
avail = cw - 26
|
||
check_fit(cell["title"], CELL_TITLE_FONT, avail,
|
||
"lane %s col %d title" % (lane["name"], ci + 1))
|
||
for ln in cell["lines"]:
|
||
check_fit(ln, CELL_NOTE_FONT, avail,
|
||
"lane %s col %d line" % (lane["name"], ci + 1))
|
||
for ci, st in enumerate(STAGES):
|
||
check_fit(st, HEAD_FONT, COLS[ci][1] - 20, "stage head %d" % (ci + 1))
|
||
if len(OVERFLOW):
|
||
for o in OVERFLOW:
|
||
print("OVERFLOW WARN " + o)
|
||
|
||
lane_h = CELL_H + LANE_GAP
|
||
bottom = MAIN_Y + len(LANES) * lane_h - LANE_GAP
|
||
total_h = bottom + 92
|
||
|
||
add('<rect x="0" y="0" width="%d" height="%d" fill="#ffffff"/>' % (W, total_h))
|
||
add('<text x="%d" y="44" font-size="%d" font-weight="700" fill="%s">%s</text>'
|
||
% (PAD, TITLE_FONT, INK, esc("采样有效性校验(adc_health)· 数据流与出口")))
|
||
add('<text x="%d" y="70" font-size="%d" fill="%s">%s</text>'
|
||
% (PAD, SUB_FONT, MUTED,
|
||
esc("三条量车道平行流过五个阶段;判定层每拍一次、常数次整数运算,输入只是计数快照")))
|
||
|
||
# ---- 阶段标题 ----
|
||
for ci, st in enumerate(STAGES):
|
||
x, cw = COLS[ci]
|
||
add('<rect x="%d" y="150" width="%d" height="34" rx="8" fill="%s" stroke="%s" '
|
||
'stroke-opacity="0.35"/>' % (x, cw, BG_HEAD, C_HEAD))
|
||
add('<text x="%d" y="172" font-size="%d" font-weight="700" fill="#334155">%s</text>'
|
||
% (x + 12, HEAD_FONT, esc(st)))
|
||
|
||
# ---- 车道 ----
|
||
for li, lane in enumerate(LANES):
|
||
color, bg = C_LANE[lane["color"]], BG_LANE[lane["color"]]
|
||
y0 = MAIN_Y + li * lane_h
|
||
# 车道标签
|
||
add('<rect x="%d" y="%d" width="%d" height="%d" rx="10" fill="%s" stroke="%s" '
|
||
'stroke-opacity="0.5"/>' % (PAD, y0, LANE_LABEL_W - 14, CELL_H, bg, color))
|
||
add('<text x="%d" y="%d" font-size="%d" font-weight="700" fill="%s" '
|
||
'text-anchor="middle">%s</text>'
|
||
% (PAD + (LANE_LABEL_W - 14) / 2.0, y0 + CELL_H / 2.0 + 5, LANE_FONT,
|
||
color, esc(lane["name"])))
|
||
|
||
for ci, cell in enumerate(lane["cells"]):
|
||
x, cw = COLS[ci]
|
||
add('<rect x="%d" y="%d" width="%d" height="%d" rx="10" fill="%s" stroke="%s" '
|
||
'stroke-opacity="0.45"/>' % (x, y0, cw, CELL_H, bg, color))
|
||
add('<text x="%d" y="%d" font-size="%d" font-weight="700" fill="%s">%s</text>'
|
||
% (x + 13, y0 + 30, CELL_TITLE_FONT, color, esc(cell["title"])))
|
||
yy = y0 + 56
|
||
for ln in cell["lines"]:
|
||
add('<text x="%d" y="%d" font-size="%d" fill="#334155">%s</text>'
|
||
% (x + 13, yy, CELL_NOTE_FONT, esc(ln)))
|
||
yy += 22
|
||
# 水平箭头到下一列
|
||
if ci + 1 < len(lane["cells"]):
|
||
nx = COLS[ci + 1][0]
|
||
cy = y0 + CELL_H / 2.0
|
||
add('<line x1="%d" y1="%.1f" x2="%d" y2="%.1f" stroke="%s" '
|
||
'stroke-width="2.2"/>' % (x + cw, cy, nx - 9, cy, color))
|
||
add('<path d="M %.1f %.1f L %.1f %.1f L %.1f %.1f z" fill="%s"/>'
|
||
% (nx, cy, nx - 11, cy - 5.5, nx - 11, cy + 5.5, color))
|
||
|
||
# ---- 底部说明 ----
|
||
add('<rect x="%d" y="%d" width="%d" height="46" rx="10" fill="#fffbeb" '
|
||
'stroke="#d97706" stroke-opacity="0.45"/>' % (PAD, bottom + 30, W - 2 * PAD))
|
||
add('<text x="%d" y="%d" font-size="%d" fill="#7c2d12">%s</text>'
|
||
% (PAD + 16, bottom + 58, FOOT_FONT, esc(FOOT)))
|
||
|
||
svg = ('<svg xmlns="http://www.w3.org/2000/svg" width="%d" height="%d" '
|
||
'viewBox="0 0 %d %d" font-family="%s">\n%s\n</svg>\n'
|
||
% (W, total_h, W, total_h, FONT, "\n".join(out)))
|
||
|
||
d = os.path.dirname(OUT)
|
||
if not os.path.isdir(d):
|
||
os.makedirs(d)
|
||
with open(OUT, "w", encoding="utf-8", newline="\n") as fp:
|
||
fp.write(svg)
|
||
ET.fromstring(svg)
|
||
print("OK %d bytes, canvas %dx%d -> %s" % (len(svg.encode("utf-8")), W, total_h, OUT))
|
||
if len(OVERFLOW):
|
||
print("!! %d 处文字可能溢出,见上方 WARN" % len(OVERFLOW))
|
||
|
||
|
||
if __name__ == "__main__":
|
||
build()
|