本文复盘一套生产级个人站点部署架构的演进全过程：从一台纯净 Ubuntu 云服务器选型加固、Nginx 进程配置，到借助 WSL2 进行本地编译复现，最终通过 GitHub Actions 打造自动化双发流水线，并基于 Linux VFS 原子系统调用实现了零停机原子切换与自动健康探测回滚机制。

1. 总体架构与四层环境职责

在实施自动化流水线前，必须首先厘清开发、构建、调度与生产这四套异构环境的职责边界。许多部署过程中的权限冲突与网络困惑，本质上都是因为混淆了执行环境：

[本地开发终端] Windows (PowerShell / VS Code)
   │ 编写 Markdown 源码、前端脚本与样式文件
   ▼
[本地编译验证] WSL2 Ubuntu (Ruby + Bundler + Node.js)
   │ 负责本地依赖管理、Jekyll 静态编译、页面元数据与死链检查
   ▼
[远端持续集成] GitHub Actions Runner (云端临时 Ubuntu 容器)
   │ 监听 main 分支推送，一次编译产物，同时向两个目标发布
   ├───────────────────────────────┬───────────────────────────────┐
   ▼                               ▼                               ▼
[目标 A：托管平台]            [网络通道：SSH/SCP]          [目标 B：自建云服务器]
GitHub Pages                 传输发布脚本与归档包            阿里云轻量应用服务器 (Ubuntu)
                                                             │
                                                             ├─ 专用 deploy 用户解压至 releases/
                                                             ├─ 校验 index.html 完整性
                                                             ├─ mv -Tf 原子替换 current 软链接
                                                             └─ Nginx 提供公网 HTTP/HTTPS 服务

1.1 环境职责划分

1.2 异构环境回环地址（127.0.0.1）语义辨析

在跨宿主机、跨虚拟化层的部署中，127.0.0.1 极易引发心智混淆。各层网络隔离边界如下：

2. 基础设施与云服务器初始化

2.1 云服务器选型与系统基线

对于托管个人静态站点及后续演进轻量级 API 服务的场景，选型基线如下：

• 硬件配额：选择 2 vCPU / 2 GiB 内存 / 40 GiB 系统盘 的轻量应用服务器。静态 Nginx 的 Master + Worker 进程常驻内存不足 25 MB，CPU 占用率低于 0.1%，剩余超 1.8 GiB 内存完全可作为 Linux 页面缓存（Page Cache）以极速响应静态文件读取，或供后续部署容器化服务；
• 操作系统：选择官方纯净的 Ubuntu 24.04 LTS x86_64 镜像，避免预装过多云厂商控制台重型组件；
• 地域选择：优先选择物理距离离核心访客最近的可用区（如深圳、广州或杭州），降低 TCP 三次握手延迟；
• 公网带宽：云厂商标注的峰值带宽（如 200 Mbps）通常受共享流量包约束，静态资源需做好 Gzip/Brotli 压缩与 HTTP 缓存头配置以降低带宽消耗。

2.2 系统加固与包管理器维护

执行位置：云服务器终端（管理员用户 admin 或 ubuntu，具有 sudo 权限）

登录云服务器后，首先更新系统包索引并应用最新安全补丁：

# 1. 刷新软件源索引
sudo apt update

# 2. 升级已安装软件包
sudo apt upgrade -y

[!IMPORTANT] 升级 OpenSSH 时的配置保留提示 当系统升级到 OpenSSH 相关包时，终端可能会弹出 /etc/ssh/sshd_config 配置冲突提示。务必选择 keep the local version currently installed（保留本地当前版本），防止云厂商预设的密钥登录配置被覆盖导致 SSH 离线失联。

升级完成后若涉及核心内核或基础 C 库变更，执行重启以刷新运行态：

sudo reboot

2.3 安装并启动 Nginx

执行位置：云服务器终端（管理员用户）

# 安装 Nginx
sudo apt install -y nginx

# 设置开机自启并立即启动
sudo systemctl enable --now nginx

# 验证本地回环连通性
curl -I http://127.0.0.1

在云控制台的安全组/防火墙规则中，确保已放行 TCP 80（HTTP） 与 TCP 443（HTTPS） 入站端口。在外部浏览器访问服务器公网 IP，若看到 Welcome to nginx! 页面，说明外部网络链路正常打通。

3. 本地构建与手动部署验证

在把一切交给 CI 自动化之前，必须先在本地完整演练一次“编译-打包-传输-发布”的手动闭环，建立基准对照。

3.1 WSL2 环境中的静态网站构建

Windows 上的源码目录（例如 E:\mydata\work\code\blog）在 WSL2 中挂载于 /mnt/e/mydata/work/code/blog。

执行位置：本地 WSL2 Ubuntu 终端（普通用户）

# 1. 检查 Ruby 与 Bundler 依赖
bundle check || bundle install

# 2. 严格模式构建静态网页（出现 front matter 语法异常立即报错中断）
bundle exec jekyll build --strict_front_matter

# 3. 运行本地预检脚本（校验元数据、死链、Sitemap 等）
node scripts/check-site.mjs

构建生成的静态网页存放在 _site/ 目录下。

3.2 规范归档打包

打包静态资源时，需要特别注意压缩路径的层级结构，必须直接打包目录内部文件，而非外层包裹目录：

执行位置：本地 WSL2 Ubuntu 终端（普通用户）

# -C _site . 表示切入 _site 目录打包其内部所有文件（含隐藏文件）
tar -czf /tmp/personal-site.tar.gz -C _site .

[!WARNING] 目录嵌套陷阱 如果打包命令错误写成了 tar -czf site.tar.gz _site，解压到服务器后将多出一层 _site 目录（变为 /var/www/personal-site/current/_site/index.html），导致 Nginx 根路径直接返回 404 或 403 错误。

3.3 手动部署与权限基线

将压缩包上传至服务器用户家目录后，在服务器端解压并校正权限：

执行位置：云服务器终端（管理员用户）

# 1. 备份原有站点（如存在）
sudo tar -czf /home/admin/nginx-html-backup.tar.gz -C /var/www/html .

# 2. 解压新版本至 Nginx 目录，--no-same-owner 避免还原打包机的 UID/GID
sudo tar -xzf /home/admin/personal-site.tar.gz -C /var/www/html --no-same-owner

# 3. 设置生产级权限掩码：目录 755，文件 644
sudo chmod -R u=rwX,go=rX /var/www/html

[!TIP] 为什么拒绝 chmod -R 777？ u=rwX,go=rX 中大写的 X 具有特殊语义：它只给目录（以及原本就具备可执行属性的文件）赋予 +x（进入目录的遍历权限），而绝不会把普通的 HTML、CSS、JS 等静态文件变成可执行文件。这既保障了 Nginx worker 进程有权限遍历目录并读取静态资源，又严格恪守了最小权限安全防线。

4. 生产级自动化发布：GitHub Actions 与安全加固

手动上传存在操作繁琐、易遗漏校验、缺乏审计记录等痛点。我们需要将整个过程交由 GitHub Actions 驱动。

4.1 最小权限原则：创建专用 deploy 用户

自动化部署属于非交互式脚本操作，坚决不能直接使用 root 或拥有无密码 sudo 权限的日常管理账号进行 SSH 登录。

执行位置：云服务器终端（管理员用户）

# 创建禁用密码登录的 deploy 用户
sudo adduser --disabled-password --gecos "" deploy

# 创建专属部署根目录并移交属主
sudo mkdir -p /var/www/personal-site
sudo chown -R deploy:deploy /var/www/personal-site

该用户无 sudo 权限，其工作空间完全隔离在 /var/www/personal-site 之内，即使 CI 密钥发生意外泄露，攻击者的横向移动面也被限制在静态站点目录之内，无法触碰系统关键配置。

4.2 部署密钥生成与严格互信配置

认证算法权衡：为什么选用 Ed25519？

步骤一：本地生成专属 Ed25519 密钥对

执行位置：本地 WSL2 Ubuntu 终端（普通用户）

ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/github-actions-deploy -N ""

步骤二：向云服务器安装公钥并限制能力

执行位置：云服务器终端（管理员用户）

# 创建并限制 .ssh 目录权限
sudo install -d -m 700 -o deploy -g deploy /home/deploy/.ssh

# 追加公钥内容，并在行首加上 restrict 限制标记
sudo tee -a /home/deploy/.ssh/authorized_keys > /dev/null <<'EOF'
restrict ssh-ed25519 AAAA...你的公钥内容... github-actions-deploy
EOF

# 固化权限（OpenSSH 强制要求，权限过宽将直接拒绝认证）
sudo chown deploy:deploy /home/deploy/.ssh/authorized_keys
sudo chmod 600 /home/deploy/.ssh/authorized_keys

[!NOTE] restrict 标记的安全隔离原理 authorized_keys 中的 restrict 关键字在不破坏 SCP 文件传输与远程管道命令执行的前提下，强制禁用了该密钥的 PTY 交互式终端分配、端口转发（Port Forwarding）、X11 转发 和 Agent 转发 能力，彻底剥夺了该密钥被黑客当作跳板渗透内网的可能。

步骤三：双向身份确认（Known Hosts）

SSH 登录不仅需要服务器验证客户端身份，客户端也必须验证服务器的主机指纹，以防范中间人劫持（MITM）：

# 1. 在云服务器上获取自身主机公钥指纹：
# 执行位置：云服务器终端
sudo ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
# 输出示例：SHA256:NeUY3NUsk2sfCTCbxGXOSFgu5GPAysIxHkPcyLkoZSE

# 2. 在本地 WSL2 中测试连接并核对指纹无误后写入 known_hosts：
# 执行位置：本地 WSL2 Ubuntu 终端
ssh -i ~/.ssh/github-actions-deploy deploy@<SERVER_IP> 'whoami'

4.3 配置 GitHub 仓库 Secrets

在 GitHub 仓库的 Settings → Secrets and variables → Actions 中，配置如下四个 Repository Secrets：

5. 零停机原子切换与自动化回滚机制

传统部署往往采用直接覆盖旧文件的方式，这种做法在生产环境中存在三项致命缺陷：

5.1 三类静态站点发布策略权衡

5.2 版本目录拓扑设计

/var/www/personal-site/
├── current -> releases/abc1234-890123-1/    <--- 稳定入口（符号链接）
└── releases/                               <--- 历史版本隔离目录
    ├── initial/                            <--- 手工备份基线
    ├── abc1234-890123-1/                   <--- 正在运行的版本 (Git Commit + Run ID)
    └── def5678-890456-1/                   <--- 上一个稳定版本（待命回滚）

Nginx 的静态站点根目录始终配置为固定的 /var/www/personal-site/current，它本身是一个软链接。发布新版本时，在后台创建新版本目录，解压并验证无误后，通过 Linux 系统调用瞬间将 current 重定向到新版本。

5.3 Nginx 根目录适配与平滑加载

修改 /etc/nginx/sites-available/default（修改前务必先执行备份）：

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    # 关键：将 root 指向符号链接 current
    root /var/www/personal-site/current;
    index index.html index.htm;

    server_name _;

    location / {
        try_files $uri $uri/ =404;
    }
}

执行位置：云服务器终端（管理员用户）

测试配置语法并向 Nginx 发送平滑重载信号：

sudo nginx -t && sudo systemctl reload nginx

本次重载后，今后版本更新只需切换软链接，无需再触动 Nginx 进程。

5.4 生产级部署与双向校验脚本设计

在仓库中新增部署核心脚本 scripts/deploy-static-site.sh。GitHub Actions 在远端通过 SSH 管道将脚本注入目标服务器执行：

脚本路径：scripts/deploy-static-site.sh（由 CI 调度以 deploy 用户身份在云服务器执行）

#!/usr/bin/env bash
set -euo pipefail

# 1. 约束版本标识格式（Commit SHA - Run ID - Run Attempt）
RELEASE_ID="${1:?Missing release_id}"
SITE_ROOT="/var/www/personal-site"
RELEASES_DIR="${SITE_ROOT}/releases"
CURRENT_LINK="${SITE_ROOT}/current"
NEW_RELEASE="${RELEASES_DIR}/${RELEASE_ID}"
ARCHIVE_PATH="${HOME}/site-${RELEASE_ID}.tar.gz"

umask 022

# 2. 检查前置软链接是否有效，记录回滚目标
if [ ! -L "${CURRENT_LINK}" ]; then
    echo "Error: ${CURRENT_LINK} is not a valid symlink!" >&2
    exit 1
fi
PREVIOUS_TARGET="$(readlink "${CURRENT_LINK}")"

# 3. 错误捕获：任何步骤异常立即触发自动回滚
rollback() {
    local exit_code=$?
    if [ ${exit_code} -ne 0 ]; then
        echo "Deployment failed! Initiating rollback to ${PREVIOUS_TARGET}..." >&2
        ln -sfn "${PREVIOUS_TARGET}" "${CURRENT_LINK}"
        echo "Previous version successfully restored." >&2
    fi
    rm -f "${ARCHIVE_PATH}"
    exit ${exit_code}
}
trap rollback EXIT INT TERM

# 4. 创建隔离的新版本目录并解压
mkdir -p "${NEW_RELEASE}"
tar -xzf "${ARCHIVE_PATH}" -C "${NEW_RELEASE}" --no-same-owner

# 5. 校验新目录首页有效性并固化权限
test -s "${NEW_RELEASE}/index.html"
chmod -R u=rwX,go=rX "${NEW_RELEASE}"

# 6. 【核心动作】原子切换软链接 (通过 ln + mv -Tf 实现不可分割的替换)
TEMP_LINK="${SITE_ROOT}/.link-${RELEASE_ID}"
ln -s "releases/${RELEASE_ID}" "${TEMP_LINK}"
mv -Tf "${TEMP_LINK}" "${CURRENT_LINK}"

# 7. 【双向深度校验】从本机 HTTP 端口拉取页面，字节级对比新版本首页
PROBE_FILE="$(mktemp)"
curl -fsS --retry 3 --retry-connrefused "http://127.0.0.1/" -o "${PROBE_FILE}"

if ! cmp --silent "${PROBE_FILE}" "${NEW_RELEASE}/index.html"; then
    echo "Verification error: HTTP response does not match newly deployed index.html!" >&2
    rm -f "${PROBE_FILE}"
    exit 1
fi
rm -f "${PROBE_FILE}"

# 8. 成功完成，解除 trap 保护
trap - EXIT INT TERM
rm -f "${ARCHIVE_PATH}"
echo "Release ${RELEASE_ID} deployed and verified successfully."

底层原理：为什么必须用 mv -Tf 而不能直接 ln -sfn？

如果直接执行 ln -sfn "releases/${RELEASE_ID}" current，在 Linux 实现中该命令并非原子操作：它本质上是先执行 unlink("current") 删除现有软链接，再执行 symlink(...) 建立新软链接。在 unlink 与 symlink 之间存在微秒级的时间窗口，此时 current 处于不存在状态。如果高并发 HTTP 请求恰好在此瞬间到达 Nginx，Worker 进程会直接报出 404 Not Found。

而通过建立临时软链接后执行 mv -Tf "${TEMP_LINK}" "${CURRENT_LINK}"，其底层调用的是 POSIX 标准的 renameat(2) / rename(2) 系统调用。在 Linux VFS 文件系统层，rename() 在目录 inode 锁保护下瞬间完成目录项指针（dentry）替换，具备硬件级原子性：并发请求要么解析到旧版本目录，要么解析到新版本目录，绝不可能观察到中间态或空链接。

[!TIP] 为什么要用 cmp 进行字节比对，而不是仅检查 HTTP 200？ 在生产环境中，仅检查 HTTP 200 极具欺骗性。如果 Nginx Worker 进程因未平滑重载导致配置未更新、或者根路径误指到了旧目录，HTTP 响应同样会返回 200 OK，但这属于典型的假死/假成功（Phantom Success）。通过将本地 curl 抓取的实时网页与本次打包的 index.html 逐字节比对（cmp --silent），能够确保 Nginx 当前输出的内容绝对来自于本次最新构建。

5.5 换行符陷阱：.gitattributes 的必要性

Windows 开发者在本地提交 Shell 脚本时，默认可能会被 Git 的 core.autocrlf 转换为 CRLF（Windows 回车换行）。当远端 Linux 执行带有 \r 的 Bash 脚本时，会直接抛出语法崩溃：

syntax error near unexpected token $'{\r'

为了从工程规范上根除此隐患，必须在仓库根目录添加 .gitattributes：

配置文件：.gitattributes（仓库根目录）

scripts/deploy-static-site.sh text eol=lf

这确保无论在任何操作系统上检出，该脚本的行尾都严格保持 LF。

6. GitHub Actions 双发流水线编排

在 .github/workflows/site-quality.yml 中编排构建与发布任务。关键原则是：同一份构建产物进行一次编译和校验，产物打包后分别投递给 GitHub Pages 与自建服务器，避免重复编译产生的哈希不一致。

工作流文件：.github/workflows/site-quality.yml

name: Site Quality and Dual Deploy

on:
  push:
    branches: [main]
  workflow_dispatch:

concurrency:
  group: pages-$
  cancel-in-progress: false

jobs:
  build-and-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Build Jekyll site
        run: bundle exec jekyll build --strict_front_matter

      - name: Verify site integrity
        run: node scripts/check-site.mjs

      # 规范打包网页归档，供后续两个部署任务复用
      - name: Package website artifact
        run: tar -czf /tmp/site-dist.tar.gz -C _site .

      - name: Upload artifact for Aliyun
        uses: actions/upload-artifact@v4
        with:
          name: aliyun-site-artifact
          path: /tmp/site-dist.tar.gz
          retention-days: 1

      - name: Upload artifact for GitHub Pages
        uses: actions/upload-pages-artifact@v3
        with:
          path: _site

  # 任务 1：发布至 GitHub Pages
  deploy-github-pages:
    needs: build-and-check
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: $
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

  # 任务 2：发布至阿里云生产服务器
  deploy-aliyun:
    needs: build-and-check
    runs-on: ubuntu-latest
    timeout-minutes: 10
    env:
      ALIYUN_HOST: $
      ALIYUN_USER: $
      ALIYUN_SSH_KEY: $
      ALIYUN_KNOWN_HOSTS: $
    steps:
      - name: Checkout repository for scripts
        uses: actions/checkout@v4

      - name: Download compiled artifact
        uses: actions/download-artifact@v4
        with:
          name: aliyun-site-artifact
          path: /tmp

      - name: Configure secure SSH environment
        run: |
          mkdir -p ~/.ssh
          chmod 700 ~/.ssh
          echo "$ALIYUN_SSH_KEY" > ~/.ssh/id_deploy
          chmod 600 ~/.ssh/id_deploy
          echo "$ALIYUN_KNOWN_HOSTS" > ~/.ssh/known_hosts
          chmod 644 ~/.ssh/known_hosts

      - name: Deliver artifact and trigger atomic switch
        run: |
          RELEASE_ID="${GITHUB_SHA}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
          
          # 1. 安全传输静态归档
          scp -i ~/.ssh/id_deploy -o IdentitiesOnly=yes \
            /tmp/site-dist.tar.gz \
            "${ALIYUN_USER}@${ALIYUN_HOST}:~/site-${RELEASE_ID}.tar.gz"

          # 2. 管道式远端执行部署与比对验证
          ssh -i ~/.ssh/id_deploy -o IdentitiesOnly=yes \
            "${ALIYUN_USER}@${ALIYUN_HOST}" \
            "bash -s -- '${RELEASE_ID}'" < scripts/deploy-static-site.sh

      - name: Cleanup credentials
        if: always()
        run: rm -rf ~/.ssh/id_deploy

7. 真实生产故障复盘：从“假成功”到真闭环

在流水线首次实战运行时，遇到了一个极具代表性的生产故障。

7.1 故障现象与反直觉假象

GitHub Actions 执行时，build-and-check 与 deploy-github-pages 全部呈现绿色通过；但在 deploy-aliyun 任务中，流水线在最后一步突然报错红灯：

Verification error: HTTP response does not match newly deployed index.html!
Deployment failed! Initiating rollback to releases/initial...
Previous version successfully restored.
Process completed with exit code 1

与此形成鲜明反差的是：外部浏览器直接访问自建服务器依然一切正常，页面并未宕机，返回 HTTP 200 OK。

7.2 根因排查证据链

登录服务器进行现场勘验，依照严密的证据链展开排查：

1. 软链接状态确认：执行 readlink /var/www/personal-site/current，软链接准确指回了上一个版本 releases/initial，证明部署脚本中的 trap rollback 自动自愈机制完全生效；
2. 新产物有效性确认：检查 releases/ 下新版本的目录，index.html 确实存在且内容完整无损；
3. Nginx 静态配置确认：查看 /etc/nginx/sites-available/default 中的 root 配置，确实已经被修改为了 /var/www/personal-site/current；
4. 【核心证据发现】进程时间戳与文件时间戳冲突： 查看 Nginx 运行进程的实际启动时间戳：

   执行位置：云服务器终端

   ps -eo pid,lstart,cmd | grep nginx
   

   证据显示：当前正在运行的 Nginx Worker 进程启动时间为 22:58，而修改 /etc/nginx/sites-available/default 配置文件的修改时间（mtime）是 23:34！

根因曝光：此前在服务器上修改 Nginx 配置文件后，仅执行了 nginx -t 语法检查，遗漏了 systemctl reload nginx 命令！

因此，Nginx Worker 进程依然在内存中沿用旧的 /var/www/html 根路径配置提供服务。当部署脚本通过 curl http://127.0.0.1/ 探测首页并与本次构建产物比对时，Nginx 返回的始终是旧站内容，直接触发了 cmp 字节校验失败。

这一真实故障闭环验证了：简单的 HTTP 200 探测只能发现服务存活，无法发现内容陈旧；深入到字节级哈希或内容比对，才能彻底杜绝假发布。

7.3 修复验证与真闭环

执行位置：云服务器终端（管理员用户）

在服务器上以管理员身份执行真正的平滑重载：

sudo systemctl reload nginx

随后在 GitHub Actions 中点击 Re-run failed jobs，流水线耗时 24 秒全部变绿。

执行位置：本地 WSL2 Ubuntu 终端

比对本地打包产物与线上实时输出的 SHA-256 摘要：

# 获取线上公网首页哈希与本地产物哈希对比
curl -s http://<SERVER_IP>/ | sha256sum
sha256sum _site/index.html

两份 SHA-256 哈希值完全吻合，站点正式达成同源自动化双发闭环。

8. 日常极简运维与秒级应急 Runbook

8.1 开发者日常心智负担归零（三步发布法）

执行位置：本地开发终端（Windows / WSL2）

随着双发自动化流水线落地，日常运维复杂度大幅收敛为标准 Git 动作：

# 1. 暂存变更
git add .

# 2. 提交说明
git commit -m "docs: 增加新技术专栏文章"

# 3. 推送触发自动化双发
git push origin main

推送后只需观察 GitHub 仓库的 Actions 图标变绿，GitHub Pages 与阿里云两处节点即在 1 分钟内完成全自动同步。

8.2 常用线上维护命令速查

执行位置：云服务器终端

# 1. 查看当前线上生效的版本标识
readlink -f /var/www/personal-site/current

# 2. 查看 Nginx 运行状态与 Worker 进程信息
systemctl status nginx --no-pager
ps -eo pid,lstart,cmd | grep nginx

# 3. 磁盘配额维护：仅保留最近 5 个版本，清理陈旧归档与目录
cd /var/www/personal-site/releases
ls -dt */ | tail -n +6 | xargs rm -rf

8.3 紧急手动秒级原子回滚 Runbook

如果在极端异常情况下（如新提交的文章存在逻辑漏洞但通过了构建校验），需要手工将云服务器紧急回滚到历史版本：

执行位置：云服务器终端（deploy 账号或具有对应权限的运维人员）

# 步骤 1：查看历史可用版本列表
ls -lt /var/www/personal-site/releases

# 步骤 2：确认目标稳定版本无误后，执行原子替换（无需重启 Nginx）
sudo -u deploy ln -sfn releases/<指定历史版本号> /var/www/personal-site/current

# 步骤 3：验证当前生效版本
readlink /var/www/personal-site/current

# 步骤 4：回环探测验证
curl -fsS http://127.0.0.1/ | head -n 5

执行软链接重置后，无需重启或重载 Nginx，公网访问即刻秒级切换回历史版本。

9. 生产环境交付与质量验收 Checklist

本方案在上线前需逐项对照如下质量门禁清单完成核验：

典型应用场景：高可靠便携仪器 / Cortex-M 裸机系统 / 脉冲动态负载 / 外部单总线库仑计 核心议题：当电池系统面临动态脉冲负载、端电压畸变、软硬件复位及单总线通信冲突时，如何构建一套可解释、能自愈且边界清晰的电量管理模块？

在嵌入式项目初期，电量估算往往容易被简化为一个“读电压查表”或“读芯片寄存器算百分比”的单一函数。然而在真实的便携设备中，工况远比静态模型复杂：高频刺激脉冲或加热负载会导致端电压剧烈抖动；单总线微秒级时序与高优先级 PWM 存在实时冲突；设备深度休眠唤醒后面临上下文丢失；充电插拔瞬间信号存在机械反弹。

如果在设计之初没有理顺边界，这些现实因素会迅速演变成一系列难以捉摸的产品缺陷：开机跳电、带载误报关机、充不满电、通信稍有扰动界面就卡死或归零。

真正健壮的电量系统，其核心不在于堆砌多复杂的拟合算法，而在于明确测量、账本、预测、显示与安全保护各自的职责边界：

• 物理测量只采集带有效性标记的硬件样本，不掺杂任何业务猜测；
• 核心账本作为电荷流动的单一事实来源（Single Source of Truth），严格按事务提交；
• 显示预测在总线受限或不可观测的窗口期维持平滑体验，绝不反向污染物理账本；
• 安全保护直连原始硬件判据，绝不等待软件滤波或显示排队；
• 异常自愈在通信中断或意外复位时最大限度保留有效事实，并在新证据建立后平滑对齐。

本文结合在 N32G455 裸机平台上的落地经验，全面复盘从底层 1-Wire 驱动、库仑积分、状态机解耦到跨复位持久化的完整架构体系。

阅读导航

• 建立整体认识：架构设计思想与可迁移核心（第 1～4 节）
• 算法与数据可信度：定点账本、速率校验与电压初值（第 5～8 节）
• 实时冲突与通信驱动：总线安全窗口与 1-Wire / DS2740 调度（第 9～11 节）
• 预测、校准与跨复位持久化：不可测区间推演、满充锚定与 BKP 连续性（第 12～14 节）
• 显示、安全保护与生命周期：展示层限速、硬件关断互锁与事件时序（第 15～18 节）
• 实战迁移与工程边界：平台适配、测试验证与踩坑清单（第 19～23 节）
• 源码导航与参考资料：关键函数速查与数据手册（第 24 节）

1. 哪些技术真正值得迁移

1.1 从“算法函数”演进为“带证据的状态系统”

许多工程师初期习惯写一个简单的电压百分比计算函数。但在实际产品落地时，系统必须严谨回答以下工程问题：

1. 当前电压的物理意义：该读数是在设备完全空闲、大功率脉冲放电，还是在充电恒压阶段采集的？
2. 电量基线的可溯源性：当前的百分比究竟基于完整的满充校准，还是基于开机时的粗略查表？
3. 故障恢复能力：单总线偶尔出现一次 CRC 校验失败，此前的容量账本是否应立即作废？
4. 上下文连续性：MCU 发生看门狗复位或从 STOP2 低功耗唤醒时，库仑计是否保持供电？期间的电荷变化能否精准补算？
5. 用户体验与真实计量：屏幕上的电量数字是否必须实时等于内部化学估计？怎样避免数字忽高忽低？
6. 保护机制的权威性：低电关机决策应当依据瞬时电压、平滑后的估算 SOC，还是独立硬件比较器？

显然，这些问题无法仅靠优化一条拟合曲线来解决。系统必须把数据源、时标、设备身份、置信度以及状态转移权限完整纳入架构模型。

1.2 可迁移核心资产清单

1.3 适用场景与应用边界

本文沉淀的架构思想特别适用于：

• 具备段码屏、OLED 或 LCD 的各类便携式仪器与手持医疗/健康设备；
• 包含脉冲负载（电刺激、微型电机、高频通信模组、超声探头等）的设备；
• 采用裸机架构、软件模拟微秒总线且无法持续轮询传感器的低功耗系统；
• 具备深度休眠唤醒流程，要求电量连续不跳变的嵌入式系统。

需要注意，本文方案针对单节锂电池体系。对于多串多并电池包，还需增加单体过欠压、均衡状态与整包有效容量管理；换用镍氢或磷酸铁锂等平坦放电曲线电池时，电压初值表及容量估算模型也必须重新标定。

2. 物理量语义与能力边界

2.1 区分电压、电流、剩余电荷与可用能量

在电化学系统中，四个关键物理量各自承担不同的数学与工程意义：

• 端电压（Voltage）：反映电池端口在当前瞬间的宏观电势，受负载、内阻及极化现象强烈调制；
• 电流（Current）：电荷在某一时刻进出电池的瞬时速率，定义充电为正、放电为负；
• 剩余电荷（Remaining Charge）：电流在时域上的积分累计结果，是电荷守恒意义上的绝对电量；
• 可用能量（Usable Energy）：放电全过程中瞬时功率 V(t) × I(t) 的积分，受终止电压门限及负载大小严重影响。

本架构的核心职责是维护高精度的电荷账本：

Q_remaining(t) = Q_baseline + ∫ I_battery(t) dt
SOC_charge     = Q_remaining / Q_capacity

若产品需要精准预估剩余可用能量（Wh）或续航剩余时间（Time-to-Empty），必须建立未来放电功率假定和端电压轨迹模型，这超出了纯库仑账本的能力范围。

2.2 为什么脉冲负载下端电压会严重失真

在直流负载模型中，端电压可作如下简化分解：

V_cell(t) ≈ OCV(SOC, T) - I(t) × R_internal - V_polarization(t)

其中电化学极化电压 $V_{polarization}$ 具有显著的时间滞后特性。当数百毫安的大电流脉冲接通时，端电压会因内阻瞬间产生明显压降，并在脉冲持续期间随极化加剧进一步下滑；脉冲切断后，端电压又需要数秒乃至数分钟才能缓慢回弹。

在实际仪器运行测试中可以清晰观察到：若在脉冲输出期间直接通过 ADC 读取端电压并查表计算 SOC，电量读数会瞬间深跌；而停机后通过库仑计核算，电池实际消耗的电荷仅占极小比例。因此，在动态带载工况下，绝不能让瞬时端电压主导电量展示。

2.3 库仑积分对绝对基线与校准的刚性需求

库仑计的核心优势在于高频精确测量“电荷进出的相对变化量 $\Delta Q$”，但它本身并不天然知晓接入电池的绝对初始电量。

如果初始粗估存在 300 mAh 的偏差，在没有权威事件重新校准前，整个充放电过程都将持续背负这 300 mAh 的系统误差。此外，毫欧级采样电阻的温漂、ADC 零点漂移以及 MCU 未计入的微小静态旁路功耗，都会随时间推移转化为微小的积分漂移。

因此，一套完整的库仑计方案必须明确回答以下逻辑链条：

• 开机第一笔电量基线从何而来？
• 什么级别的事件具备重新校准绝对原点的权威性？
• 校准后如何保证坐标系在软硬件复位中持续平滑有效？
• 一旦发生何种物理异常，必须果断宣布基线失效？

2.4 容量假设与 SOH 学习的边界

在许多基础工程中，额定容量往往硬编码为固定值（例如 4000 mAh）。此时 SOC = 100% 仅代表当前电荷账本达到了标称设定值，并不意味着电池实际仍能完整放出 4000 mAh。

电芯健康度（SOH）涉及循环老化、低温衰减以及放电截止条件。如果在缺乏高精度完整充放电闭环的前提下贸然编写自适应学习逻辑，往往会因瞬态异常数据把标称容量越学越偏，最终固化为永久性系统误差。因此在工程实现中，首要任务是确保物理计量的确定性与连续性，切忌在基础未扎实时盲目引入容量学习。

3. 总体架构：五条链路与一个状态所有者

3.1 跨层次数据流与控制流

系统在物理硬件、核心调度与展示保护之间建立了清晰的分级链路：

[电池电流] ──> [采样电阻 / DS2740] ──> [1-Wire 驱动] ──> [候选样本校验]
                                                               ↓
[BATT/REF ADC] ──> [有界批次采样] ──> [初始基线准入] ──> [真实容量账本] <──> [BKP 寄存器]
                                                               ↑
[充电 IC 硬件引脚] ──> [500ms 硬件去抖 / FULL 锚定判定] ────────┘

[真实容量账本] ────────────┐
[多通道负载 / 加热模型] ──┴─> [显示目标抉择] ──> [UI 限速/单向滤波] ──> [快照发布 / 屏幕刷新]

[BATT/REF ADC] ────────────> [独立硬件欠压保护]（直接控制系统生死）
[充电 IC 硬件引脚] ──────────> [底层 PWM 执行点互锁]（周期性硬切断加热输出）

注意：欠压关机与电量展示虽然在物理上共用同一组 ADC 转换通道，但逻辑判据完全独立，低电保护绝不受电量算法中间状态的干扰。

3.2 模块职责分工

• onewire.c：底层物理层。负责 GPIO 开漏配置、微秒级时基延时、Reset/Presence 握手、字节级位操作与时钟活性检测。
• ds2740.c：芯片驱动层。负责 ROM 码读取校验、CRC8 校验、Status 寄存器配置及双读一致性校验。
• battery_manager.c：业务核心层。负责维护主电荷账本、多维可信度流转、安全窗口仲裁、显示平滑与跨复位持久化。
• main.c（展示模块）：负责将对外发布的结构体快照映射为 LCD 段码或图符。
• main.c（保护模块）：负责开机瞬态电压核验与运行期 9 批中位值投票欠压关机。
• n32g45x_it.c / ChargPrg()：在最底层定时器中断及充电状态机中，硬性关断加热等功率输出。

3.3 单一所有权与对外接口规范

系统内部定义唯一的私有上下文静态变量 s_bm，真实剩余量 remaining_counts 由其统一管辖。外部模块只能通过规范的对外 API 触发操作或读取不可变快照：

/* 初始化与周期轮询 */
void BatteryManager_Init(void);
void BatteryManager_Process(void);

/* 事件驱动请求与低功耗准备 */
void BatteryManager_RequestSample(void);
void BatteryManager_PrepareForStop(void);

/* 读取系统只读快照 */
void BatteryManager_GetSnapshot(BatterySnapshot *snapshot);

其中 RequestSample() 仅发出调度标记，不在当前调用栈执行阻塞通信；PrepareForStop() 在进入低功耗前完成最后一笔合规数据的保存和状态冻结。

3.4 公共快照字段语义

对外发布的 BatterySnapshot 结构体提供完整、明确的数据视图：

typedef struct
{
    uint32_t remaining_counts;       /* 核心账本绝对剩余量 (counts) */
    uint16_t estimated_soc_percent;  /* 内部计算目标 SOC (0~100) */
    uint16_t soc_percent;            /* 经过 UI 限速与单向滤波后的显示 SOC */
    int32_t  current_ua;             /* 最近一次硬件测得的物理电流 (μA) */
    uint16_t voltage_mv;             /* 最近有效滤波端电压 (mV)，0 代表无效 */
    BatteryConfidence confidence;    /* 当前对外部展示数据的置信度 */
    BatteryState state;              /* 核心状态机枚举 */
    ChargeState charge_state;        /* 经去抖后的业务充电状态 */
    uint16_t fault_flags;            /* 硬件故障分类位图 */
} BatterySnapshot;

4. 状态模型：解耦正交维度

4.1 五大正交维度的分离

许多电量模块的 Bug 源于试图用一个统一的 State 枚举表达所有现象。事实上，系统在任意时刻均由五个互不冲突的正交维度决定：

1. 绝对基线是否建立：内部是否拥有经过有效事件确认的电荷原点；
2. 基线的权威程度：该原点是通过粗估电压查表建立，还是通过充满电硬件锚定建立；
3. 物理总线健康度：芯片在线、通信超时、CRC 损坏还是时序异常；
4. 外部充电语义：空闲未充、充电恒流中、充满断开还是状态引脚悬空；
5. 显示层展示模式：直随物理账本、跟随模型预测还是故障平滑冻结。

将这五个维度拆开后，诸如“通信偶发超时但历史满充基线仍然完全可信”的场景便能得到清晰的边界解耦，避免一报错就引发全局变量清零。

4.2 账本状态机流转

                  [上电复位 / BKP 校验通过]
                             │
                             ▼
[未初始化 UNINITIALIZED] ──> [正常跟踪 TRACKING] <──┐
           │                         │              │
           │ (充满信号有效且经确认)   │ (重新校准)   │ (通信恢复且连续)
           ▼                         ▼              │
    [满充锚定 FULL_ANCHORED] ───────────────────────┤
                                     │              │
                           (连续 3 次通信严重故障)   │
                                     ▼              │
                             [计量故障 GAUGE_FAULT] ─┘

• UNINITIALIZED：系统开机且无有效持久化记录，等待电压稳定或充满事件；
• TRACKING：已建立基准，依据每笔通过校验的物理增量驱动账本；
• FULL_ANCHORED：满充事件已完成权威基线校准，正处于最高精度坐标系；
• GAUGE_FAULT：总线连续失败达到门限。此时保留历史基准，可信度降级，等待总线自愈。

4.3 必须严格守护的八大系统不变量

在进行任何代码修改或平台移植时，必须保证以下八条核心不变量（Invariants）绝不破损：

1. 样本准入铁律：未通过物理速率校验与双读一致性的 ACR 数据，严禁推进核心账本和参考时间戳；
2. 单向隔离原则：显示平滑滤波与负载预测消耗，绝不能反写进真实硬件电荷账本；
3. 权威优先原则：一旦建立了有效连续账本，动态带载电压与充电端电压严禁强行覆盖账本；
4. 故障语义分级：单总线偶发物理通信错误，绝不等同于计量芯片掉电；
5. 未知不等于零：未建立初始基准时对外报 NONE，绝不能向 UI 伪造 0% 导致误关机；
6. 校准条件严谨：满充校准依赖持续稳定的物理引脚电平与合法硬件 ACR，绝不依赖“UI 是否已显示 100%”；
7. 安全关断最高优先级：低电关机与加热切断必须直连底层硬件判据，绝不等待显示层或主循环状态机慢慢排队；
8. 跨复位自愈前提：只有在芯片身份（ROM）与复位标志（RNAOP）双重确认连续时，才允许基于历史 ACR 补算。

5. 库仑账本：单位推导、定点计算与模差处理

5.1 原始数据拒绝过早截断

DS2740 采样寄存器返回 16 位补码数据。在将物理寄存器换算为对外展示的百分比前，必须在内部保持高精度定点计数（counts）。

以 4000 mAh 电池为例，1% 的电量相当于 40 mAh。如果驱动层过早把每次采样转换为整数百分比，每次只有零点几毫安时的消耗都会在整除中被抹去，累积数小时后将造成严重的漏计。

5.2 换算基准与参数推导

在案例工程中，硬件采用 $R_{sns} = 20\text{ m}\Omega$ 采样电阻，芯片配置为 DS2740U。

根据官方数据手册，各物理量单位换算如下：

ACR 分辨率 = 6.25 / R_sns(mΩ) = 6.25 / 20 = 0.3125 mAh / count
配置额定容量 = 4000 mAh
总容量对应 counts = 4000 / 0.3125 = 12800 counts

DS2740U 瞬时电流分辨率 = 1562.5 / R_sns(mΩ) = 1562.5 / 20 = 78.125 μA / LSB

在 C99 源码中，通过定点整数避免浮点开销：

#define BM_CAPACITY_COUNTS ((BM_CAPACITY_MAH * BM_RSNS_MOHM * 4) / 25)

/* 瞬时电流定点换算 (μA) */
int32_t current_ua = ((int32_t)raw_current * 15625) / (10 * BM_RSNS_MOHM);

5.3 16 位有符号模差算法解析 ACR 回绕

库仑计的累积电荷寄存器（ACR）会在 16 位边界（0x0000 与 0xFFFF 之间）发生自然的自然溢出回绕。如果直接用 32 位无符号减法，溢出时会算出数万 counts 的虚假跳变。

系统采用严格的 16 位有符号模差算法：

int16_t delta = (int16_t)(uint16_t)(new_acr - old_acr);
remaining = clamp(remaining + POLARITY * delta, 0, CAPACITY_COUNTS);

通过两个典型工况验证补码回绕的正确性：

• 放电越界回绕：上次采样 old = 0x0004，本次读到 new = 0xFFFE。 new - old = 0xFFFE - 0x0004 = 0xFFFA（16位无符号）。 强制转为 int16_t 后精确得到 $-6\text{ counts}$，准确反映放出 6 counts 电荷。
• 充电越界回绕：上次采样 old = 0xFFFC，本次读到 new = 0x0003。 new - old = 0x0003 - 0xFFFC = 0x0007。 强制转为 int16_t 精确得到 $+7\text{ counts}$，准确反映充入 7 counts 电荷。

该算法成立的前提是：两次采样之间真实的净电荷变动必须落在有符号半量程（$\pm 32767\text{ counts}$）之内。在 20 mΩ 下，32767 counts 对应超过 10240 mAh，远大于整包电池容量，因此在常规轮询周期下具备坚不可摧的数学可靠性。

6. 事务级样本接收机制

6.1 候选缓冲与两阶段提交

总线通信不可避免地会受到电磁干扰或接触抖动。驱动设计严守“两阶段提交”模式：

[读取硬件寄存器] ──> [局部 candidate 临时结构体]
                              │
                    [严格完整性与速率校验]
                              │
                    ┌─────────┴─────────┐
                 [合格]               [异常]
                    │                   │
                    ▼                   ▼
           [正式吸收入账]          [果断丢弃 candidate]
           [推进 last_good_tick]   [保留历史账本与参考点]

如果粗暴地直接将原始数据读入全局上下文再去判断合法性，一旦校验失败，系统将被迫处于半更新的污染状态。

6.2 速率校验的时间窗口锚定

物理世界中电池电流存在物理上限。系统通过校验单次增量是否超越物理极限，有效拦截异常干扰帧：

允许最大增量 limit = I_max × (当前时间 - 上次有效样本时间) + 余量

这里的关键工程细节是：计算时间差必须使用 last_good_tick（上次成功被系统接受的样本时间），绝不能使用 last_attempt_tick（上次尝试通信的时间）。

如果使用尝试时间，当总线因外部干扰连续失败两次并在第 15 秒成功恢复时，时间差会被错误算成 5 秒，导致累计了 15 秒物理电荷的合规数据被当成“超速大跳变”错误拒绝，最终陷入“通信越重试、恢复越失败”的死锁。

7. ADC 采样：成对校验与有效性优先

7.1 成对比值滤波

电压采集采用芯片内部精确基准 REF（1.20V / 2.048V 等）与分压后的电池端通道 BATT 联动测量：

V_cell(mV) = (BATT_raw × V_ref_mv) / REF_raw

系统按批次采集 8～12 组样本。每采入一组立即计算比值，最终对这批比值进行排序，取中心均值滤波。

为什么不能分别对 BATT 数组和 REF 数组取中位数后再相除？ 在数学上，比值的中位数并不等价于中位数的比值：

当电源轨在采样瞬间出现纹波抖动时，单独排序可能会把第 1 次的尖峰 BATT 与第 8 次的低谷 REF 强行拼在一起，凭空捏造出一个从未真实存在过的离谱电压。

7.2 测量失效与电池欠压的严格区分

当 ADC 轮询超时、硬件分压偏置未开启或基准通道异常时，系统严格将数据标记为 voltage_valid = 0，向对外接口发布 0 mV 作为无效哨兵值。

上层业务逻辑绝不能因为“读数失效”就顺理成章地当成“0V 电池放空”执行紧急关机，否则任何底层的偶发采样时序抖动都会导致整机意外死机。

8. 无基线初始化：审慎使用开路电压

8.1 开路电压查表的苛刻准入条件

当系统彻底断电冷启动、且 BKP 中没有任何历史记录时，系统只能借助静态电压估算初始 SOC。但该入口受到极其严格的互锁保护：

bool BM_IdleVoltageAllowed(void)
{
    return (!have_baseline) &&                     /* 1. 仅限无基线状态 */
           (voltage_valid) &&                      /* 2. 电压采样有效 */
           (raw_charge_state == CHARGE_IDLE) &&    /* 3. 硬件未充电 */
           (Pwr1 == 0 && Pwr2 == 0) &&             /* 4. 脉冲输出关闭 */
           (TIM1_CH1_Disabled && TIM8_CH1N_Disabled); /* 5. 硬件底层输出真正静默 */
}

只有当系统确认既无大功率放电、又无充电电流注入时，才允许调用 12 点分段线性插值表建立第一个粗略的 TRACKING 基准。

8.2 12 点参考曲线与插值规范

当前采用的 12 点典型常温开路电压（OCV）参考映射表如下：

相邻电压点之间采用标准的整数定点线性插值。需要明确，该曲线仅作为冷机上电时的粗略落脚点，一旦库仑计开始正常工作，该表即刻退出舞台，绝不允许在后续运行中周期性强行查表修正。

9. 实时冲突：总线安全窗口机制

9.1 微秒级延时与高优先级脉冲输出的冲突

软件模拟 1-Wire 协议要求严苛的微秒级时序：主机拉低 500 μs 复位、并在特定 15～60 μs 采样窗口内读取从机电平。在此期间，MCU 必须临时关闭全局中断（__disable_irq()）。

然而，工程中的高优先级任务（例如驱动高频功率开关管或脉冲变压器的 TIM 互补 PWM、以及负责实时安全监控的定时器中断）要求微秒级确定性响应。如果在高占空比输出过程中强行执行 1-Wire 通信，长达数百微秒的关中断会直接导致硬件输出波形失真；反之，若在 1-Wire 期间不关中断，中断抢占又会摧毁总线时序，导致通信频繁超时。

9.2 软件意图与底层硬件双重闭锁

解决该冲突的核心方案是总线安全窗口机制（Safe Bus Window）：

bool BM_GaugeBusSafe(void)
{
    /* 软件业务层认为已停止 */
    bool soft_idle = (Pwr1 == 0 && Pwr2 == 0);

    /* 底层硬件定时器比较输出引脚已真正物理关闭 */
    bool hard_idle = ((TIM1->CCER & (TIM_CCER_CC1E | TIM_CCER_CC2E)) == 0) &&
                     ((TIM8->CCER & (TIM_CCER_CC1NE | TIM_CCER_CC2NE)) == 0);

    return soft_idle && hard_idle;
}

只有当上层意图和底层硬件输出同时处于静默状态时，才允许启动 1-Wire 事务。若窗口不满足，主循环平滑推迟总线采样，绝不强行打断实时输出。

9.3 通信挂起期间硬件独立积分

软件暂停通信并不等同于硬件暂停计量。

在脉冲输出期间，虽然 MCU 停止读取 DS2740，但库仑计芯片本身由电池持续供电，其内部独立的模拟积分器和计数器依然在以极高精度默默记录流经采样电阻的每一微库伦电荷。当脉冲输出结束、安全窗口重新开启时，MCU 仅需读取一次最新的 ACR 寄存器，即可通过 16 位模差一次性补全整个输出期间消耗的全部电荷。

10. 1-Wire 驱动：时序、临界区与容错退出

10.1 独立硬件微秒时基

驱动摒弃了不可靠的 for 循环空指令延时，采用独立定时器 TIM2 构建确定性时基：

• 定时器主频 64 MHz，预分频系数设为 63，得到标准的 1 MHz 自由运行向上计数器（1 tick = 1 μs）；
• 自动重装载寄存器设为 0xFFFF，支持自然的 16 位溢出回绕；
• 超时计算全部采用模差：(uint16_t)(TIM2->CNT - start_us) < timeout_us。

10.2 严格规范的临界区保护

在关键读写时序中，关中断必须遵循“保存现场—恢复现场”规范，严禁粗暴调用全局开中断：

/* 正确写法：保存调用者的原始中断屏蔽状态 */
uint32_t primask = __get_PRIMASK();
__disable_irq();

/* 执行极微秒级总线位操作 */

__set_PRIMASK(primask); /* 精确恢复原有状态，不踩踏上层嵌套 */

10.3 双重有限循环 Guard 防御

在等待总线电平翻转时，若硬件总线因外部短路持续锁死在低电平，单纯依赖时钟判决可能会因时钟异常陷入死循环。

系统在所有等待宏中加入了有限循环计次门限（Guard Count）：

#define OW_WAIT_LEVEL(level, max_us, guard) do { \
    uint16_t start = (uint16_t)TIM2->CNT; \
    uint32_t cnt = 0; \
    while (GPIO_ReadInputDataBit(...) != (level)) { \
        if ((uint16_t)(TIM2->CNT - start) >= (max_us)) return OW_TIMEOUT; \
        if (++cnt >= (guard)) return OW_BUS_ERROR; \
    } \
} while(0)

通过“时基超时”与“最大指令循环上限”双重防护，彻底杜绝外设硬件故障导致 CPU 主循环假死。

11. DS2740 驱动与主循环协作调度

11.1 芯片复位侦测技巧（RNAOP 位利用）

DS2740 具备一个专用状态寄存器（Status Register）。其中的 RNAOP（Read Net Address Opcode）位在上电时的硬件默认值为 0。

驱动在每次成功完成初始化后，主动将 RNAOP 置为 1。在后续的周期性巡检中，若发现该位意外变回了 0，即可作为库仑计自身发生过掉电复位的决定性铁证，从而果断废除旧坐标系，防止按错误的参考点累计。

11.2 主循环非阻塞协作状态机

为了将耗时较长的单总线事务平摊到各个调度周期中，BatteryManager_Process() 被设计为一个分步推进的状态机：

[IDLE 周期等待] ──> [STEP_ADC 单组采集] ──> [STEP_GAUGE 安全读芯片] ──> [STEP_FUSE 融合发布]
       ▲                                                                       │
       └───────────────────────────────────────────────────────────────────────┘

每个主循环仅推进一个有限子步骤（例如仅采集一组 ADC，或仅执行一次受控读取），单步耗时控制在毫秒级以内，确保主循环对按键、UI 和保护判据保持毫秒级流畅响应。

12. 显示预测：在不可测区间提供平滑体验

12.1 引入独立显示预测的必要性

在脉冲电刺激输出期间，为了规避实时冲突，1-Wire 通信完全挂起。如果界面直接冻结不变，用户会误以为设备卡死；若直接拿带载电压查表，电量又会瞬间跳水。

系统的解决方案是构建轻量级展示预测层（Display Prediction Layer）：

真实电荷账本 remaining ──(脉冲期间冻结等待补算)─────────────────> 停机后一次性模差补齐
                                                                   │
负载工况模型推演 ───────> [显示预测器 stim_remaining] ──> [UI 目标] ──> UI 限速展示

预测模型仅负责在总线挂起期间计算一个合理的“假想目标”，指导 UI 平滑走字，该数据绝不反写进底层的硬件真实账本。

12.2 双通道负载电流模型与静态功耗扣除

单通道脉冲在不同档位下的平均等效电流基于实测物理曲线分段插值：

在推导双通道复合工况时，必须扣除整机基础静态功耗 $I_{base}$（约 27 mA），防止基础功耗被重复叠加两次：

12.3 微安·毫秒定点积分与余数保留

预测模块在主循环中累积消耗。定义基本计算单位为：

在每次循环迭代中，必须将不足 1 count 的微小余数精准保存在 fraction 变量中：

uint64_t consumed = (uint64_t)model_current_01ma * elapsed_ms + fraction;
uint64_t delta_counts = consumed / UNITS_PER_COUNT;
fraction = consumed % UNITS_PER_COUNT; /* 余数无损滚入下一轮 */
predicted_remaining -= delta_counts;

如果直接丢弃除法余数，由于主循环调度周期极快（每次仅消耗微小的几分之一 count），截断误差会导致预测模型“跑不动”，即使输出持续数分钟，预测电量也纹丝不动。

12.4 档位切换时先积旧档、再切新档

当检测到用户按键调整了脉冲档位时，计算顺序必须严格遵循因果依赖：

1. 第一步：使用旧档位电流与流逝时间 $\Delta t$，将上一阶段的实际电荷消耗积分入账；
2. 第二步：将当前观察到的新档位存入上下文，作为下一阶段的计算基准。

如果颠倒顺序，系统会错误地用崭新的高档位电流去反溯之前低档位区间的消耗，人为放大估算误差。

13. 满充校准：事件权威与幂等控制

13.1 充电信号引脚的业务语义

系统通过硬件上拉检测充电芯片的两只漏极开路指示脚（CHARG 与 STDBY，低电平有效）：

13.2 信号去抖与一次性幂等锚定

充满校准绝不能仅凭瞬态脉冲直接触发，必须经过两级可靠性确认：

1. 时序去抖：FULL 状态在硬件引脚上连续稳定保持至少 500 ms，排除插入和拔出瞬间的机械抖动；
2. 安全锚定：在总线安全窗口内取得最新合法 ACR 后，执行原子校准：
   • 将账本 remaining_counts 重置为额定最大值（12800 counts）；
   • 将当前的 last_acr 设为全新基准参考点；
   • 将基线可信度提升为最高等级 ANCHORED，并持久化到 BKP；
   • 置位 full_done 标志，确保在设备插着线满电静置的数小时内，只执行一次基线重置，绝不周期性反复覆盖正常的静态待机微小损耗。

14. 跨复位持久化：守护上下文连续性

14.1 为什么持久化不能只存一个 SOC 百分比

许多系统习惯在休眠前把电量存为 85%。但在唤醒恢复时，该数值无法告诉系统：

• 85% 究竟对应多少物理电荷？
• 库仑计当时的内部累积寄存器停在哪个刻度？
• 睡眠期间库仑计是否一直在正常走字？
• 唤醒后的第一笔新电量应该相对哪个原点进行差分？

如果只存百分比，系统在唤醒后将彻底失去连续跟踪能力，只能重新依赖端电压粗估查表，造成频繁的“睡醒电量突变”。

14.2 BKP V3 精确存储布局与校验

系统使用 MCU 内部由备用电源维持的 备份数据寄存器（BKP_DAT1～DAT12），总计 24 字节：

14.3 最小提交协议（Commit Protocol）

在写入备份域时，系统采用严格的写入时序保证原子性：

BKP_Write(DAT1, 0x0000); /* 第一步：先清空 Magic，将旧记录显式作废 */

/* 第二步：按序写入版本号、物理参数、身份码和计算出的全新 CRC16 */
BKP_Write(DAT2, VERSION);
...
BKP_Write(DAT12, crc16_value);

BKP_Write(DAT1, 0x2740); /* 第三步：最后一步回写 Magic，完成正式提交 */

如果在写入中途 MCU 发生断电或意外复位，重启时由于 DAT1 != 0x2740，系统能准确识别出这是一条“未完成的半截废数据”，果断放弃恢复并重新初始化，绝不加载被破坏的数据。

14.4 校验恢复流水线与补算

在开机恢复时，BM_TryRestore() 顺序通过七重安全门禁：

1. DAT1 Magic 匹配且 CRC16 严格通过；
2. 存储版本号完全一致；
3. 容量配置与系统宏定义一致；
4. 现场读出的 64 位芯片 ROM 码与存储的一致（防止电池包或从板被热替换）；
5. 现场读出的芯片 RNAOP 标志位仍为 1（证明库仑计自身未发生过掉电复位）；
6. 存储的 ACR 与现场读到的 ACR 模差在合理容量边界内；
7. 恢复出的剩余电量落在 $0 \sim \text{Capacity}$ 合法区间。

门禁全部通过后，系统通过模差算法补全休眠期间的全部电量变动：

系统随后将当前 ACR 刷新为最新起点。整个恢复过程完全不需要读取电压，实现了平滑无缝的电量延续。

15. UI 展示层：平滑滤波与单向约束

15.1 三层数值解耦

[物理账本 SOC]  ──> 依据真实电荷积分，毫秒级反映微小进出
       │
[内部目标 SOC]  ──> 融合刺激预测与故障保持后的计算目标
       │
[展示层 UI SOC] ──> 面向用户的最终平滑视图，严格遵守步进与单向约束

三层解耦保证了：内部对物理世界了如指掌，而对外展现给用户的是一个稳定、合乎直觉的仪表盘。

15.2 核心展示平滑规则

1. 步进限速：UI 显示每 5000 ms 内最多只能变动 1 个百分点，消除任何因算法切换导致的数字跳动；
2. 放电单向约束：在未接入充电器的正常使用期（CHARGE_IDLE），UI 电量绝对不允许向上反弹；
3. 充电单向约束：在充电状态（CHARGING / FULL）下，UI 电量绝对不允许向下倒退；
4. 异常保持：通信偶发故障或信号抖动时，UI 坚定冻结显示上一次的合法百分比，避免闪烁；
5. 未知与真零分离：未建立有效基准时，屏幕隐藏百分比或显示破折号；只有真实电荷耗尽时才显示“0%”。

16. 安全保护与硬件互锁

16.1 低电关机严禁依赖 UI 估算值

显示层为了用户体验添加的限速和单向滤波，在功能安全领域统称为“延迟与失真”。

如果将低电关机的判据绑定在“UI 变为 0%”上，当大电流突发负载将端电压拉低到保护板即将截断的临界点时，UI 可能还在以每 5 秒 1% 的速度慢吞吞递减。这将导致设备尚未提示用户保存就直接被硬件保护板猝死切断，甚至引发 Flash 写入崩溃。

因此，低电关机必须直连底层的独立硬件 ADC 判据：

• 采集真实的 BATT 端电压；
• 采用 8 组中位值滤波形成批次；
• 采用 9 批连续滑动投票机制（超过 5 批低于 3.309V 门限即刻触发紧急关机流程）；
• 保护逻辑完全独立于任何电量估算代码。

16.2 经典 Bug 复盘：主循环单次关热为什么会被中断踩踏

在包含加热功能的设备中，曾出现过一个极为隐蔽的软硬件竞态缺陷： 当用户插入充电器时，主循环虽然检测到了充电状态，并调用函数将加热引脚拉低（HOTEN_OFF）；但此时用户之前设定的温度档位全局变量仍停留在“中档”。

负责产生加热 PWM 调制信号的底层定时器中断（TIM5 ISR）每隔 100 毫秒执行一次：中断一触发，代码按当前的“中档”重新计算占空比，并再度将加热引脚拉高（HOTEN_ON）。结果导致主循环的单次关热指令被底层中断反复践踏，使得设备在充电时依然偷偷发热。

16.3 最终执行点硬件互锁（Defensive Sink）

正确的工程解法是在最终硬件输出汇合处建立不可逾越的安全互锁：

/* TIM5 中断服务函数中，最靠近硬件输出寄存器的唯一出口 */
void TIM5_IRQHandler(void)
{
    /* 1. 硬件级首要互锁：直接读取充电引脚的原始电平 */
    if (GPIO_ReadInputDataBit(CHARG_PORT, CHARG_PIN) == Bit_RESET ||
        GPIO_ReadInputDataBit(STDBY_PORT, STDBY_PIN) == Bit_RESET)
    {
        /* 只要插着线，底层无条件切断加热开关管，直接忽略任何上层软件档位 */
        HOTEN_OFF();
        return;
    }

    /* 2. 正常工况下，才允许根据上层档位配置 PWM 占空比 */
    Apply_Heater_PWM();
}

将安全互锁从脆弱的上层业务页面下沉到物理执行的最终汇合点，无论上层逻辑发生多严重的调度错乱、任务阻塞或变量残留，底层硬件安全都能得到绝对保证。

17. 完整生命周期事件演进

为了清晰呈现各模块的协同，下表梳理系统在关键生命周期节点中的行为：

[冷机上电] ──> 探测 1-Wire ──> BKP 校验失败 ──> 满足空闲条件 ──> 电压查表建初值 ──> 启动跟踪
     │
[正常运行] ──> 周期 ADC 滤波 ──> 安全窗口读 ACR ──> 16位模差入账 ──> UI 限速 1%/5s 刷新
     │
[启动脉冲] ──> 硬件输出开启 ──> 挂起 1-Wire ──> 模型定点积分 ──> UI 预测走字
     │
[停止脉冲] ──> 硬件输出关闭 ──> 窗口恢复 ──> 读最新 ACR ──> 一次性模差补齐 ──> 清除预测态
     │
[插入充电] ──> 底层 ISR 硬切断加热 ──> 充电去抖 500ms ──> UI 转为单向递增
     │
[满充锚定] ──> STDBY 稳定 500ms ──> 读取有效 ACR ──> 重置 100% 基线 ──> 写入 BKP ──> 保持幂等
     │
[准备休眠] ──> 调用 PrepareForStop ──> 封存最后有效数据 ──> 提交 BKP ──> 进入 STOP2
     │
[唤醒重启] ──> 读 BKP ──> 七重门禁全过 ──> 模差补算休眠损耗 ──> 零跳变恢复运行

18. 跨平台移植与最小抽象层设计

当需要将本套电量架构移植到 STM32、GD32、ESP32 或搭载 RTOS 的新项目中时，切忌全盘复制代码。应当优先为核心模块实现以下六个最小硬件抽象层（HAL）接口：

/* 最小硬件适配接口草案 */
typedef struct
{
    uint32_t (*get_now_ms)(void);                       /* 单调递增毫秒时钟 */
    bool     (*is_hardware_safe)(void);                 /* 硬件是否处于安全访问窗口 */
    bool     (*read_battery_mv)(uint16_t *voltage_mv);  /* 读取有效端电压 */
    bool     (*read_gauge_sample)(Ds2740Sample *sample);/* 读取底层硬件库仑计 */
    ChargeRawState (*read_charger_pins)(void);          /* 读取充电引脚瞬时物理电平 */
    bool     (*bkp_save_record)(const BatteryRecord *r);/* 持久化写入 */
    bool     (*bkp_load_record)(BatteryRecord *r);      /* 持久化读取 */
} BatteryPlatformOps;

通过将具体的时钟树配置、定时器寄存器操作以及 BKP 驱动收敛到底层接口中，battery_manager.c 中的状态机、模差计算、显示限速和预测逻辑可以实现 100% 纯逻辑无缝跨平台复用。

19. 工程踩坑排查清单

在调试便携电量管理系统时，以下是最容易踩中的技术隐患：

1. 电阻单位混淆：代码中的 BM_RSNS_MOHM 宏使用的是毫欧（如 20）。若误写成欧姆（0.02）或微欧（20000），将彻底摧毁整个定点换算体系；
2. 假死在关中断区：1-Wire 等待循环务必加入 Guard Count，防止因上拉断开导致 MCU 永久死锁在临界区；
3. 把尝试时间当有效时间：速率校验如果绑定了重试时间戳，通信故障恢复后必定引发虚假超速报警；
4. 充满后 UI 滞后不是 Bug：满充锚定瞬时将内部账本重置为 100%，而 UI 需遵守 1%/5s 限速。从 85% 追赶到 100% 约需 75 秒，这是为了兼顾用户体验的刻意设计；
5. 休眠期间 BKP 供电：MCU 备份域若依赖电池直供，必须确保在整机主 LDO 关断时，VBAT 引脚仍有可靠备电，否则无法实现跨睡眠连续恢复；
6. 边充边用场景极性相反：若仪器支持插线运行，必须仔细核对采样电阻的位置是串在“纯电池支路”还是“系统总电源支路”，否则充电时开启大功率输出会被诊断逻辑误判为“极性接反故障”。

20. 核心源码锚点与参考资料

20.1 关键逻辑速查

20.2 外部资料与规范

• Analog Devices DS2740 官方数据手册：用于核对 16 位补码物理意义、RNAOP 与 SMOD 状态寄存器位定义；
• ARM Cortex-M4 编程手册：深入理解 PRIMASK 临界区保护规范与硬件单周期指令行为。

设计目标与物理约束

这套记录存储需要满足以下要求：

1. 掉电原子性：在记录写入、单条删除、整表清空或扇区整理的任意字节/指令边界断电，重启后不得出现半写脏数据被误判为有效记录、已有有效记录丢失或显示序号错乱。
2. 硬实时与看门狗安全：主循环运行 AD7190 约 2.4 kHz 连续采样与 8 行条带 LCD 刷新，独立看门狗（IWDG）超时窗口约 1 s。任何保存、删除、清空确认或后台擦除都严禁在主循环中原地阻塞等待 Flash 内部耗时。
3. 支持 O(1) 整表清空与单条原位删除：
   • 用户执行“清空全部”时必须立即生效，不能在按键确认路径中同步擦除数十个 4 KiB 扇区；
   • 用户执行“单条删除”后，列表显示序号动态重排为连续的 1..N，但不能为了顺延序号而重写 Flash 中后续数百条记录。
4. 受控的稀疏扇区空间回收：单条删除积累到一定程度后，按需把稀疏扇区中仅存的有效记录安全迁移到追加扇区并擦除回收源扇区，且避免通用 KV 文件系统的高 RAM 开销与写放大。

分区规划与容量预算

系统选用 W25Q128（16 MiB）顶部的 156 KiB（0xFD9000～0xFFFFFF） 作为记录专用分区，共包含 39 个 4 KiB 物理扇区：

容量与余量计算

• 扇区内部结构：每个 4 KiB（4,096 B）数据扇区划分为 64 个固定 64 字节槽位——槽 0 固定为 64B 数据扇区头，槽 1～63 为 63 个数据记录槽。
• 产品上限与物理预留：
  • 当前产品可见记录上限设为 1,000 条，最多占用 ceil(1000 / 63) = 16 个数据扇区；
  • 物理分区一次规划支持 2,000 条（需 ceil(2000 / 63) = 32 个数据扇区）；
  • 36 个数据扇区共提供 36 × 63 = 2,268 个物理记录槽；扣除强制保留的 至少 2 个经整扇区验证为 0xFF 的全空扇区（EMPTY） 后，仍开放 34 × 63 = 2,142 个槽位，足以容纳 2,000 条有效记录及 142 个过渡/掉电脏槽。

64 字节定长槽编码与两阶段提交

为消除编译器结构体对齐与填充差异，所有记录槽固定为 64 字节，统一使用显式小端函数（PutU16/PutU32、GetU16/GetU32）序列化。

数据记录槽布局（Format V3）

两阶段提交（Two-Phase Commit）写流程

NOR Flash 页编程如果在写正文中途断电，会留下部分字节已写、部分字节仍为 0xFF 的半写槽。为此，所有数据记录、扇区头和控制记录均严格执行两阶段提交：

阶段 1（写正文与 CRC）：
  ├─ 目标槽 64 字节必须处于全 0xFF 擦除态（ERASED）
  ├─ 序列化偏移 0..58 正文与 61..62 的 CRC-16
  ├─ 偏移 59..60 (lifecycle) 保持 0xFFFF，偏移 63 (commitFlag) 保持 0xFF
  ├─ 启动单页非阻塞编程并轮询 BUSY 清零
  └─ 整槽 64 字节读回，逐字节比对正文、CRC 及 commitFlag == 0xFF

阶段 2（单独写提交字节）：
  ├─ 仅对偏移 63 发起 1 字节页编程：0xFF → 0x00
  ├─ 轮询 BUSY 清零后读回确认 commitFlag == 0x00
  └─ 更新 RAM 中的可见记录数、下一内部 ID 与扇区有效计数

定长槽 C99 结构体定义

#pragma pack(push, 1)
typedef struct
{
    uint32_t magic;          /* 偏移 0..3: ASCII 魔数标识 (如 0x52454344 'RECD') */
    uint8_t  version;        /* 偏移 4: 格式版本号 (当前为 3) */
    uint8_t  recordType;     /* 偏移 5: 记录类型 (1=数据记录, 2=世代/迁移控制记录) */
    uint16_t recordLen;      /* 偏移 6..7: 固定为 64 字节 */
    uint32_t generation;     /* 偏移 8..11: 世代号 (整表逻辑清空时单调递增) */
    uint32_t recordId;       /* 偏移 12..15: 世代内稳定自增主键 (1..N，删除不重排) */
    uint8_t  payload[43];    /* 偏移 16..58: 43 字节通用业务数据载荷 (时间戳、测量结果、状态等) */
    uint16_t lifecycle;      /* 偏移 59..60: 原位生命周期码 (0xFFFF=有效, 0xA55A=已删除, 0x5AA5=已迁移) */
    uint16_t crc16;          /* 偏移 61..62: CRC-16/MODBUS (仅覆盖偏移 0..58 正文) */
    uint8_t  commitFlag;     /* 偏移 63: 独立提交标志 (0xFF=未提交/脏槽, 0x00=已正式提交生效) */
} RecordSlot64;
#pragma pack(pop)

两阶段提交核心写入实现

/* 两阶段安全提交：先写正文与 CRC，校验无误后再单独将 commitFlag 编程为 0x00 */
bool RecordStore_Write2PC(uint32_t flashAddr, RecordSlot64 *slot)
{
    uint8_t readback[64];

    /* 阶段 1：写入偏移 0..62 的正文与 CRC，保持 commitFlag 为 0xFF */
    slot->commitFlag = 0xFF;
    slot->crc16 = Crc16_Modbus((const uint8_t *)slot, 59);

    if (!Flash_PageProgram(flashAddr, (const uint8_t *)slot, 63))
    {
        return false;
    }
    Flash_WaitBusy();

    /* 读回校验阶段 1 数据是否完整写入 */
    Flash_Read(flashAddr, readback, 64);
    if (memcmp(readback, slot, 63) != 0 || readback[63] != 0xFF)
    {
        return false; /* 发生半写或断电，当前槽成为 DIRTY 脏槽，绝不提交 */
    }

    /* 阶段 2：单独对偏移 63 发起 1 字节编程：0xFF -> 0x00 */
    uint8_t commitByte = 0x00;
    if (!Flash_PageProgram(flashAddr + 63, &commitByte, 1))
    {
        return false;
    }
    Flash_WaitBusy();

    /* 读回确认 commitFlag 是否成功变为 0x00 */
    Flash_Read(flashAddr + 63, &commitByte, 1);
    return (commitByte == 0x00);
}

启动扫描时，每个 64 字节槽被严格归为三类：

• ERASED（全 0xFF）：干净空槽，仅当前追加扇区尾部的连续 ERASED 槽可用于分配新记录；
• VALID（commitFlag == 0x00 且版本、长度、CRC-16 全部正确）：有效已提交记录；
• DIRTY（任何非全 0xFF 但未提交或 CRC 错误的槽）：掉电残槽，扫描时直接跳过、绝不原地覆写，留待整扇区回收时一并擦除。

交互式在线演示：两阶段提交与掉电故障注入模拟

下面的模拟器按 64 字节槽展示写入、提交、删除和逻辑清空。可以在阶段 1 中途模拟断电，再执行上电扫描，查看哪些槽会被识别为有效记录。它只演示恢复规则，实际 Flash 的时序和掉电行为仍需上板验证。

三扇区世代控制环与逻辑清空

为什么“清空全部”不擦除数据扇区

若在用户确认清空时同步擦除全部数据扇区，耗时可达数秒并触发看门狗复位。本架构引入 32 位 generation（世代号）：

1. 三扇区控制环轮转：3 个控制扇区（每个可顺序追加 64 条 64B 控制记录）保持“1 个当前追加 + 1 个全 0xFF 备用空扇区 + 1 个空或待后台补擦扇区”的稳态。
2. 确认路径只追加 1 条世代记录：用户长按 5 秒并确认清空后，仅在控制环尾部按两阶段提交写入 1 条新 generation 记录（耗时 < 10 ms）。提交成功的瞬间，RAM 中可见记录数立即归零、nextRecordId 重置为 1，旧世代记录因 record.generation != currentGeneration 自动在逻辑上不可见。
3. 跨世代共用当前追加扇区：逻辑清空不会封闭当前正在追加的数据扇区。只要该数据扇区尾部仍有 ERASED 空槽，新世代记录会继续紧接着旧世代记录往后追加，直到写满 63 槽才启用下一个全空扇区。这样不必在每次“保存几条就清空”后立即擦除数据扇区。
4. 控制环后台擦除：仅当活动控制扇区写满 64 条切换到备用空扇区后，后台状态机才对已退役的旧控制扇区发起非阻塞 4 KiB 擦除并逐页验证回填为全 0xFF（约每 64 次清空才触发 1 次控制扇区擦除）。

原位生命周期码与单条删除

稳定主键与动态显示序号分离

每条记录拥有不可变的内部主键 {generation, recordId}，而 UI 列表展示的序号 1..N 是按当前可见记录顺序实时计算的索引：

• 删除请求通过 {generation, recordId} 精确定位目标槽，拒绝跨世代、不存在或已删除目标；
• 删除中间某条记录后，其余记录的 recordId 保持不变，列表显示序号自然顺延为连续的 1..(N-1)，无需改写其他记录。

利用 NOR Flash 特性的单向生命周期码

偏移 59..60 的 16 位 lifecycle 字段独立于正文 CRC 之外，利用 NOR Flash 允许将 1 编程为 0 的特性实现三次状态跃迁：

0xFFFF (ACTIVE：正常可见记录)
  │
  ├── 用户单条删除 (1 → 0 页编程) ──► 0xA55A (DELETED：逻辑已删除，不可见、不迁移)
  │
  └── 稀疏迁移复制完成 (1 → 0)   ──► 0x5AA5 (MIGRATED：目标副本已提交，等待源扇区擦除)

• 0xA55A 与 0x5AA5 均只能从 0xFFFF 单向写入，互不转换；
• 单条删除只需对目标槽偏移 59..60 执行 2 字节页编程（0xFFFF → 0xA55A）并读回验证，耗时仅约 4 ms；
• 一旦 0xA55A 读回确认成功，逻辑删除立即生效，后续即便稀疏整理因空间或异常延后，已删除记录也绝不会在重启后“复活”。

原位单条删除核心实现

/* 单条记录原位墓碑删除：利用 NOR Flash 1->0 特性将 lifecycle 编为 0xA55A */
bool RecordStore_DeleteInPlace(uint32_t slotAddr)
{
    uint16_t currentLife = 0;
    Flash_Read(slotAddr + 59, (uint8_t *)&currentLife, 2);
    if (currentLife != 0xFFFF)
    {
        return false; /* 已被删除或非有效记录 */
    }

    uint16_t tombstone = 0xA55A;
    if (!Flash_PageProgram(slotAddr + 59, (const uint8_t *)&tombstone, 2))
    {
        return false;
    }
    Flash_WaitBusy();

    Flash_Read(slotAddr + 59, (uint8_t *)&currentLife, 2);
    return (currentLife == 0xA55A);
}

稀疏扇区非阻塞迁移与掉电续作

触发条件与目标扇区选择

每次单条删除提交成功后，检查目标记录所在的 4 KiB 数据扇区：

• 一个数据扇区共有 63 个数据槽，当其中属于当前世代的 ACTIVE 记录数 > 21 条时，不触发整理，直接结束；
• 当 ACTIVE 记录数降至 ≤ 21 条（即逻辑空闲达到 2/3） 时，触发稀疏扇区非阻塞整理：
  1. 优先复用当前追加扇区（fit 路径）：若源扇区不是当前追加扇区，且当前追加扇区尾部剩余连续 ERASED 空槽数 >= 源扇区 ACTIVE 记录数，直接将有效记录迁移到当前追加扇区尾部；
  2. 按需启用全空扇区（new 路径）：若当前追加扇区尾部空间不足，或源扇区本身就是当前追加扇区，则从数据池中挑选 1 个经校验全为 0xFF 的 EMPTY 扇区（启用后仍必须至少保留 2 个 EMPTY 扇区），先两阶段提交新扇区头，再将其作为迁移目标。

掉电安全的五步迁移协议

为防止迁移中途断电导致记录丢失或出现双份重复记录，控制环引入 MIGRATE_BEGIN 与 MIGRATE_COMMIT 事务日志，按以下状态机分步推进：

1. 写 MIGRATE_BEGIN 控制记录（两阶段提交）
   └─ 持久化冻结 {事务序号, 源扇区索引/分配序号, 目标扇区索引/分配序号}

2. 逐槽扫描源扇区，对每条当前世代 ACTIVE 记录执行：
   ├─ (a) 在目标扇区尾部两阶段提交完整副本（保留原 generation 与 recordId）
   └─ (b) 目标副本读回确认后，将源记录 lifecycle 从 0xFFFF 编程为 0x5AA5 (MIGRATED)

3. 源扇区全部 ACTIVE 记录复制并标记完毕后：
   └─ 写 MIGRATE_COMMIT 控制记录（两阶段提交），宣告数据所有权正式移交目标扇区

4. 对源扇区发起非阻塞 4 KiB 擦除 (SectorEraseStart + PollOperation)

5. 按 256B 页逐页读回校验源扇区 4,096 字节全为 0xFF：
   └─ 校验通过后将源扇区重新登记为 EMPTY 空扇区，释放迁移事务锁

四个持久化边界断电/复位自愈规则

上电扫描分类与容灾状态机

typedef enum {
    SLOT_STATE_ERASED = 0, /* 全 0xFF 空槽，可用于追加新记录 */
    SLOT_STATE_VALID,      /* 正常提交的有效记录 */
    SLOT_STATE_DELETED,    /* 逻辑墓碑已删除记录 (0xA55A / 0x5AA5) */
    SLOT_STATE_DIRTY       /* 校验失败或掉电半写脏槽，直接跳过并在整扇区回收时擦除 */
} SlotState;

SlotState RecordStore_ScanSlot(uint32_t slotAddr, RecordSlot64 *outSlot)
{
    RecordSlot64 slot;
    Flash_Read(slotAddr, (uint8_t *)&slot, sizeof(RecordSlot64));

    /* 1. 检查是否为全 0xFF 干净擦除槽 */
    if (IsAllErased((const uint8_t *)&slot, sizeof(RecordSlot64)))
    {
        return SLOT_STATE_ERASED;
    }

    /* 2. 检查两阶段提交标志 */
    if (slot.commitFlag != 0x00)
    {
        return SLOT_STATE_DIRTY; /* 断电半写脏槽，直接跳过 */
    }

    /* 3. 校验魔数、版本与正文 CRC-16 */
    if (slot.magic != 0x52454344 || slot.recordLen != 64 ||
        slot.crc16 != Crc16_Modbus((const uint8_t *)&slot, 59))
    {
        return SLOT_STATE_DIRTY; /* CRC 损坏，判定为无效脏槽 */
    }

    /* 4. 检查生命周期码 */
    if (slot.lifecycle == 0xA55A || slot.lifecycle == 0x5AA5)
    {
        return SLOT_STATE_DELETED; /* 已被原位删除或已迁移 */
    }

    if (outSlot != NULL)
    {
        *outSlot = slot;
    }
    return SLOT_STATE_VALID;
}

基于 J-Link RTT 的板级故障注入与 HIL 验收

为在不破坏量产固件安全性的前提下验证上述状态机，工程通过默认关闭的编译开关 APP_RECORD_STORE_VALIDATION_ENABLE 隔离测试状态机，在 J-Link RTT Channel 0 上提供非阻塞验证指令集。

核心 RTT 验证指令与注入点

record_status                      # 查看记录服务只读状态 (generation/count/next/empty)
record_test codec                  # 运行 64B 槽固定向量与异常分支纯 RAM 自检
record_test cleanup                # 擦除并逐页校验 39 个扇区 (0xFD9000..0xFFFFFF)
record_test append <N>             # 非阻塞批量追加 N 条测试记录
record_test delete_pos first|middle|last  # 删除首/中/末条可见记录并自动验证重复删除拒绝
record_test full_probe             # 满容量时探测第 1001 条返回 FULL 且介质零改动
record_test list_check             # 正序/倒序遍历全部页面，校验连续显示序号 1..N
record_test migrate_probe fit|new  # 自动触发 22→21 条稀疏扇区迁移（复用追加扇区 / 启用新扇区）
record_test inject migrate_begin|migrate_copy|migrate_mark|migrate_commit # 4 个持久化边界复位注入
record_test inject erase_start|erase_timeout|erase_verify                 # 3 种擦除故障边界注入

实机目标板（N32G455 + W25Q128）验证结果汇总

在基于 Cortex-M4 与 SPI NOR Flash 的实机硬件测试板上，执行全套 RTT 故障注入与压力验证，关键实测数据如下：

验证收尾规范：全部破坏性测试结束后，再次执行 record_test cleanup 将 39 个扇区恢复为空白世代 1，随后将 APP_RECORD_STORE_VALIDATION_ENABLE 恢复为 0 重新编译量产固件，确保生产镜像中输入 record_test 仅返回 no support now。

阅读目标与相关文件

阅读时可以对照这几个问题：

• UI 数据、页面状态和 LCD 驱动之间如何分层；
• 为什么没有使用整屏帧缓冲，而是使用 8 行高的渲染条带；
• RGB565 像素如何通过全屏坐标裁剪写入条带缓冲；
• SPI1 为什么同时启用 TX DMA 和 RX DMA；
• DMA 完成为什么不等于 SPI 已经发送完毕；
• 中断、主循环和 DMA 如何协同，又如何避免缓冲区被提前改写；
• 屏幕方向切换、背光、超时恢复分别在什么时机执行；
• 当前实现的性能、边界和仍需硬件确认的事项。

核心显示链路分为四个解耦的子系统：

整体显示分层模型

显示链路自顶向下分为 6 个阶段：

传感器与设置数据
  → AppRuntimeData（运行数据快照）
  → AppUiContext（页面状态和待显示值）
  → AppUiRenderer（一帧不可变快照）
  → AppUiCanvas（240 × 8 RGB565 条带缓冲）
  → AppUiDisplay（显示适配层）
  → LcdSt7789（窗口命令与 SPI1 DMA）
  → LCD GRAM（屏内显存）

每层只负责一类职责：

最核心的设计边界是：LCD 驱动模块不保存整屏画面，它只把 UI 交给它的一块像素内存传送到屏幕。 页面怎么画、画什么内容，完全由 UI 层决定。

硬件连接与信号含义

在典型的 4 线 SPI 彩屏接口中，包含以下硬件引脚定义：

代码按 ST7789、SPI Mode 0、32 MHz 工作，这属于当前软件配置与现有实现，移植或更换屏幕批次时仍须结合屏幕规格书与逻辑分析仪实测确认。

SPI1 时钟与模式配置

LCD 初始化通过 LcdSt7789_ConfigGpio() 完成 GPIO、SPI1、DMA1 时钟和 DMA 中断配置。

时钟来源

系统时钟与 SPI1 分频关系如下：

SYSCLK = 128 MHz
HCLK   = 128 MHz
PCLK2  =  64 MHz（HCLK / 2）
SPI1   = PCLK2 / 2 = 32 MHz

SPI1 工作模式

手动控制 CS 和 RS 的原因是 LCD 协议不只是连续字节流。在一次刷新前，软件要依次完成“发命令、发参数、切换为像素数据、保持 CS 有效”等步骤。

初始化 GPIO 时先写安全电平

drv_lcd_st7789.c 先写输出数据寄存器，再把引脚切成推挽输出模式：

• CS 先置高，避免误选中屏幕；
• RS 先置高，保持普通数据态；
• RST 先置低，屏幕保持复位；
• BL 先关闭，避免屏幕显存未初始化时闪出随机内容；
• SCK 先置低，匹配 SPI Mode 0 空闲电平。

这样可以避免 GPIO 模式切换瞬间产生肉眼可见的背光闪烁或被屏幕误识别为命令的毛刺。

LCD 上电初始化与背光时机

LcdSt7789_Init() 的执行顺序如下：

1. 配置 GPIO、SPI1、DMA1 和 NVIC；
2. 关闭背光（PC2 置低）；
3. RST 拉低 20 ms，再拉高并等待 120 ms；
4. 发送 SWRESET (0x01) 软件复位，等待 150 ms；
5. 发送 SLPOUT (0x11) 退出睡眠，等待 120 ms；
6. 发送 RDDID (0x04)，经过一个 dummy byte 后读取 3 个 ID 字节；
7. 发送 COLMOD (0x3A) = 0x55，选择 16 bit/pixel 的 RGB565 像素格式；
8. 发送 MADCTL (0x36) = 0x00，选择默认正向扫描；
9. 依次发送 INVON (0x21)、NORON (0x13) 和 DISPON (0x29)；
10. 等待 UI 把第一整帧（40 个条带）画完后再开启背光。

需要注意两点：

1. 当前 RDDID 只判断 SPI 传输是否超时，未将读回的 3 字节与固定 ID 强校验。因此 LcdSt7789_Init() 返回 true 代表“ID 读取事务完成”。
2. 初始化期间 LCD GRAM 的内容不保证是有效页面。如果复位后立即开背光，用户可能看到随机花屏。因此固件坚持在 UI 完成首帧全部 40 个条带（nextY >= 320）后才调用 AppUiDisplay_BacklightOn() 打开背光（100% 档位为持续高电平，40%～88% 档位为 TIM4 软件 PWM）。

RGB565 格式与 LCD 地址窗口

RGB565 16 位像素表示

COLMOD = 0x55 将像素格式配置为 RGB565：

Bit:  15          11 10               5 4            0
     +--------------+------------------+--------------+
     | Red: 5 bits  | Green: 6 bits    | Blue: 5 bits |
     +--------------+------------------+--------------+

常见纯色值：红色 0xF800、绿色 0x07E0、蓝色 0x001F、白色 0xFFFF、黑色 0x0000。

UI 的像素缓冲类型是 uint16_t。发送像素前，SPI1 从 8 位模式切换到 16 位模式并保持 MSB first，每个半字按高位到低位发出，正好对应 RGB565 的线上顺序；像素传输完成后，驱动再把 SPI1 恢复为 8 位，以便发送下一组 LCD 命令。

矩形窗口设置

屏幕内部有独立 GRAM。MCU 在发送像素之前，先用 LcdSt7789_SetWindow() 设定目标矩形窗口：

1. CASET (0x2A)：设置起始列 x0 和结束列 x1；
2. RASET (0x2B)：设置起始行 y0 和结束行 y1；
3. RAMWR (0x2C)：通知屏幕后续数据是 GRAM 像素；
4. RS 拉高、CS 拉低；
5. 连续发送 width × height 个 RGB565 像素。

结束坐标包含端点，计算关系为 x1 = x + width - 1、y1 = y + height - 1。条带缓冲按行优先排列，LCD 内部地址自动递增，将线性像素流依次填入矩形窗口。

渲染条带（Strip Rendering）与帧快照机制

为什么用 8 行条带代替整屏缓冲

240 × 320 分辨率下，每像素 2 字节，完整 RGB565 帧缓冲需要：

240 × 320 × 2 = 153,600 bytes (150 KiB)

这已超过 N32G455REL7 的 144 KiB 总 SRAM。因此固件只分配 8 行高度的条带缓冲：

#define UI_RENDER_STRIP_ROWS (8U)
uint16_t pixels[240 * 8];

条带缓冲大小仅为 240 × 8 × 2 = 3,840 bytes，是整屏缓冲的 1/40；完整一帧被拆成 320 / 8 = 40 个条带，用分次绘制和 DMA 调度换取极低的 RAM 占用。

单条带生成流程与坐标裁剪

AppUi_RenderProcess() 在每轮主循环中每次只推进一条带：

if LCD still busy:
    return

if a new frame starts:
    capture an immutable frame snapshot

if all 320 rows are complete:
    end frame and turn on backlight
    return

prepare canvas for rows nextY .. nextY + 7
draw current page, clipped to those rows
start asynchronous DMA for that strip
nextY += stripHeight

为什么调用完整页面绘制函数却只改写 8 行？关键在 AppUiCanvas_FillRect() 和 AppUi_DrawGlyphBits() 的裁剪逻辑：

• 页面绘制代码继续使用 (0..239, 0..319) 的全屏坐标；
• 基础绘图原语先判断图形矩形与当前条带 [appUiCanvas.y, appUiCanvas.y + 7] 是否相交；
• 不相交则立即跳过；相交时把全局纵坐标转换为条带内偏移 drawY - appUiCanvas.y，只改写条带缓冲中的第 0..7 行。

这种“用 CPU 换 RAM”的架构使业务页面无需为条带编写复杂的分段布局代码，代价是同一页面的布局函数在一帧内会执行 40 次。

条带画布上下文与全屏矩形裁剪实现

typedef struct
{
    uint16_t stripY;          /* 当前条带在全屏中的起始 Y 坐标 (0..312, 步进 8) */
    uint16_t stripHeight;     /* 当前条带高度 (固定为 8) */
    uint16_t pixels[240 * 8]; /* 8 行 RGB565 像素缓冲 (3,840 字节) */
} StripCanvas;

static StripCanvas s_canvas;

/* 全屏矩形填充在当前条带上的动态裁剪算法 */
void Canvas_FillRect(int16_t x, int16_t y, int16_t w, int16_t h, uint16_t color)
{
    int16_t stripTop = (int16_t)s_canvas.stripY;
    int16_t stripBottom = (int16_t)(stripTop + s_canvas.stripHeight);

    /* 1. 垂直方向快速剔除：若目标矩形完全在当前条带上方或下方，直接跳过 */
    if ((y + h <= stripTop) || (y >= stripBottom))
    {
        return;
    }

    /* 2. 计算在条带局部的有效扫描行范围 [localY0, localY1) */
    int16_t localY0 = (y < stripTop) ? 0 : (int16_t)(y - stripTop);
    int16_t localY1 = (y + h > stripBottom) ? (int16_t)s_canvas.stripHeight : (int16_t)(y + h - stripTop);

    /* 3. 水平方向边界夹紧 [clipX0, clipX1) */
    int16_t clipX0 = (x < 0) ? 0 : x;
    int16_t clipX1 = (x + w > 240) ? 240 : (int16_t)(x + w);
    if (clipX0 >= clipX1) return;

    /* 4. 仅改写落在当前 8 行内的局部缓冲区 */
    for (int16_t ly = localY0; ly < localY1; ly++)
    {
        uint16_t *row = &s_canvas.pixels[ly * 240];
        for (int16_t lx = clipX0; lx < clipX1; lx++)
        {
            row[lx] = color;
        }
    }
}

帧快照与重绘请求合并

一帧由 40 次主循环、40 次绘制和 40 次 DMA 组成。如果每条带都直接读取实时力值或菜单焦点，上半屏可能画旧值、下半屏画新值，造成同一帧内部自相矛盾。

因此一帧开始时，渲染器将当前页面、菜单焦点、已格式化力值、电池百分比、波形快照及预计算的曲线纵坐标、设置页文本统一复制到 AppUiRenderer 快照中，在 40 个条带全部发完前保持不变，从而保证逻辑上的帧一致性。

同时，AppUi_RequestRedraw() 不会堆积刷新队列，只将 appUiRenderer.pending 置 1：

• 同一时刻连续发生多次数据变化，只合并为“需要再画一帧”；
• 当前帧传输期间若有新变化，pending 标志保留，待当前帧第 40 条带结束后抓取最新快照开始下一帧。

交互式在线演示：240×8 条带渲染与帧快照防撕裂模拟

下面的演示每次绘制 8 行，从第 0 条带（y=0..7）推进到第 39 条带（y=312..319）。关闭“帧快照”后，可以观察数据在一帧中途变化时，数字上下部分不一致的现象。整屏缓冲区需要 153.6 KB，条带缓冲区为 3.84 KB。

SPI1 全双工 DMA 与三态异步状态机

TX DMA 与 RX DMA 协同配置

一个 8 行条带包含 1,920 个像素（30,720 bits）。LcdSt7789_DrawPixelsAsync() 使用 DMA1_CH2 发送像素，同时启用 DMA1_CH1 接收丢弃：

为什么只写屏幕还必须配置 RX DMA？因为 SPI 是全双工移位结构，MOSI 每发出 16 位像素，MISO 也会移入 16 位数据。若不取走接收数据，接收寄存器会产生未读数据并触发 OVR（Overrun）标志。用内存不递增的 RX DMA 将无用数据排空到静态变量 lcdAsyncRxDiscard，既无需分配 3,840 字节接收缓冲，又能以“最后一个接收半字取走”作为全双工传输完成的可靠基准。

为什么 DMA 完成不等于 SPI 传输结束

必须区分三个硬件阶段：

1. TX DMA 把最后一个像素写入 SPI1->DAT；
2. SPI 将该数据装入内部移位寄存器，RX DMA 收完倒数第二个字并在最后一个字移入后触发 RX TC 中断；
3. SPI 硬件确保总线上最后一位真正移出并令 SPI_I2S_BUSY_FLAG 清零。

如果收到 DMA 中断就立刻拉高 CS，最后一个像素可能仍在移位或刚离开移位器，导致屏幕尾像素截断。因此驱动采用三态状态机：

LCD_ASYNC_IDLE（空闲，可接受新条带）
  │
  ├─ 配置窗口并启动 RX/TX DMA
  ▼
LCD_ASYNC_TRANSFER（DMA 搬运中）
  │
  ├─ RX DMA 完成中断置位 lcdAsyncDmaDone = 1
  ▼
LCD_ASYNC_WAIT_SPI（主循环等待 SPI BUSY 清零）
  │
  ├─ SPI BUSY == 0（或 200 ms 超时恢复）
  ▼
关闭 DMA 与中断 → 拉高 CS → SPI 恢复 8 bit → 回到 LCD_ASYNC_IDLE

异步传输状态机与中断服务程序

typedef enum {
    LCD_STATE_IDLE = 0,     /* 空闲，可接受新条带 */
    LCD_STATE_TRANSFERRING, /* DMA 搬运像素中 */
    LCD_STATE_WAIT_SPI_DONE /* DMA 完成，等待 SPI 硬件移位寄存器排空 */
} LcdAsyncState;

static volatile LcdAsyncState s_lcdState = LCD_STATE_IDLE;

/* DMA 接收完成中断服务程序 (仅更新状态与清除中断挂起，绝不阻塞) */
void DMA1_Channel1_IRQHandler(void)
{
    if (DMA_GetFlagStatus(DMA1_FLAG_TC1))
    {
        DMA_ClearFlag(DMA1_FLAG_TC1);
        s_lcdState = LCD_STATE_WAIT_SPI_DONE;
    }
}

/* 主循环非阻塞推进函数 */
void Lcd_Process(void)
{
    if (s_lcdState == LCD_STATE_WAIT_SPI_DONE)
    {
        /* 严禁在 DMA ISR 中拉高 CS，必须等待 SPI 硬件 BUSY 清零 */
        if (!SPI_IsBusy(SPI1))
        {
            LCD_CS_HIGH();               /* 拉高片选，结束像素事务 */
            SPI_SetDataWidth8Bit(SPI1);  /* 恢复 8 位命令模式 */
            s_lcdState = LCD_STATE_IDLE; /* 释放条带所有权，允许 UI 绘制下一条带 */
        }
    }
}

极简 ISR 与主循环收尾

DMA1_Channel1_IRQHandler 转发给 LcdSt7789_DmaRxIrqHandler()，中断服务程序只做三件事：

• RX DMA 错误时置 lcdAsyncDmaError = 1；
• RX DMA 完成时置 lcdAsyncDmaDone = 1；
• 清除 DMA1_CH1 全局中断挂起位。

ISR 不等待 SPI BUSY、不切 SPI 位宽、不打日志，也不启动下一条带。LCD 中断的抢占优先级为 3，AD7190 采样中断为 1；这里只记录标志，收尾交给主循环中的 LcdSt7789_Process() 执行。

单条带完整时序与主循环串联

AppUi_RenderProcess()
  1. 在 240×8 缓冲中裁剪绘制当前条带 (y .. y+7)
  2. 调用 LcdSt7789_DrawPixelsAsync(0, y, 240, 8, pixels)
       ├─ 8-bit 轮询发送 CASET + RASET + RAMWR
       ├─ RS=1, CS=0 保持，SPI1 切换为 16-bit
       ├─ 先使能 RX DMA (CH1)，再使能 TX DMA (CH2)
       └─ 状态置为 TRANSFER，立即返回 true
  3. UI 将 nextY += 8 并返回主循环，主循环继续处理采样/按键/看门狗
  ...
DMA1_Channel1_IRQHandler()
  4. 1,920 个像素搬运完毕，置 lcdAsyncDmaDone = 1 并清中断
  ...
下一轮主循环：
  5. AppRuntimeData_Process() 更新实时数据
  6. LcdSt7789_Process() 检测到 dmaDone，进入 WAIT_SPI
  7. 确认 SPI BUSY == 0，关 DMA、拉高 CS、恢复 8-bit、状态回 IDLE
  8. AppUi_Process() 见 IsBusy() == false，立即绘制并提交下一条带

需要注意的是：“释放条带缓冲”是所有权移交概念——在 LcdSt7789_IsBusy() 返回 false 之前，UI 绝不能修改或覆盖 pixels 数组。

性能估算与屏幕方向切换

理论与实际帧率

在 SPI1 32 MHz、16 bit RGB565 下，理论纯像素速率为 32,000,000 / 16 = 2,000,000 pixel/s：

• 单个 240 × 8 条带（1,920 像素）纯传输时间约 0.96 ms；
• 整屏 40 个条带（76,800 像素）纯传输时间约 38.4 ms（理论极限约 26 fps）。

计入每条带的 CASET/RASET/RAMWR 命令开销、40 次布局裁剪计算、主循环收尾间隔以及高优先级 AD7190 采样的穿插后，实际刷新率面向测量仪表式的 10 Hz（100 ms 周期）内容更新设计，兼顾视觉响应与采样实时性。

屏幕方向在帧边界切换

屏幕正向（MADCTL = 0x00）与 180° 反向（MADCTL = 0xC0）只能在两帧之间切换。AppUi_ProcessOrientation() 仅在满足以下全部条件时才写 MADCTL：

• 目标方向有效且与当前方向不同；
• 当前没有正在分条带生成的一帧；
• LcdSt7789_IsBusy() == false。

若在一帧中途修改 MADCTL，已发出的上半帧与后续条带会使用相反的扫描坐标系，导致画面上下割裂。方向切换成功后会立即触发一次整屏重绘。

常见误区与排查速查

常见认识误区

• 误区一：DMA 完成中断一到就可以立刻改写像素缓冲——不可以，必须等主循环 LcdSt7789_Process() 确认 SPI BUSY 清零并将状态切回 IDLE。
• 误区二：启用 RX DMA 说明正在从屏幕读回图像——不是，正常刷屏时 RX DMA 仅用于排空全双工移位器防止 OVR，并作为完成事件基准。
• 误区三：有帧快照就完全没有物理撕裂——帧快照保证同一帧内的业务数值与曲线自洽，但屏幕仍按 40 个条带从上往下写入 GRAM，未使用双帧缓冲或 TE 同步信号。

典型故障排查方向

字号规划与 Flash 体积预算

在 512 KB Flash 的 MCU 上，如果直接嵌入完整 GB2312 或 Big5 字库，仅单个字号就会消耗数百 KB 空间。因此工程按 UI 视觉层级定义了 5 套按需子集化的 1-bit 点阵字库：

五套字库点阵数据合计仅 19,664 字节（约 19.2 KiB），全部以 const uint8_t 存入片内 Flash，运行期零 RAM 占用。

1-bit 点阵二进制格式

所有字库统一采用 1 bit/pixel、行优先（Row-major）、高位在左（MSB leftmost） 的紧凑编码格式：

• 每个字节的最高位（bit7）对应该行最左侧像素，bit0 对应右侧第 8 个像素；
• 单行像素宽度不足 8 的整数倍时，行末低位补 0；
• 每行字节数计算公式：stride = (width + 7) / 8；
• 单个字形总字节数：size = stride × height。

典型字形尺寸计算示例：

16×16 汉字：stride = (16 + 7) / 8 = 2 B/行  →  单个字形 = 2 × 16 = 32 B
 8×16 ASCII：stride = (8 + 7) / 8 = 1 B/行  →  单个字形 = 1 × 16 = 16 B
24×24 汉字：stride = (24 + 7) / 8 = 3 B/行  →  单个字形 = 3 × 24 = 72 B
24×40 数字：stride = (24 + 7) / 8 = 3 B/行  →  单个字形 = 3 × 40 = 120 B

为什么 16 px 繁体汉字必须用原生点阵而非矢量缩放

在 16×16 的极低分辨率下，台湾繁体字（如“歸”“斷”“輸”“壓”“籤”）笔画极其密集。如果直接将桌面端 TrueType/OpenType 矢量字体缩放到 16 px 再做二值化阈值裁剪，相邻横画与撇捺会严重粘连成实心黑块，导致小屏幕完全无法辨认。

为此，字库生成流水线采用了按字号分源的策略：

此外，构建脚本对上游标准字库文件执行 SHA-256 哈希强校验，确保在不同开发环境或 CI 中重新生成都能得到逐字节完全一致的 C 源码数组。

/* 正在生成 C99 const uint8_t 数组... */

Unicode 升序索引表与二分查找

为了在 ARMCC 5 下避免 GBK/UTF-8 源文件编码混用问题，所有字库检索表统一按 Unicode 码点（uint16_t codepoint）升序排列：

typedef struct
{
    uint16_t codepoint; /* Unicode 码点，如 '荷' = 0x8377 */
    uint8_t  width;     /* 字形像素宽度：ASCII 为 8/12，汉字为 16/24 */
    uint8_t  size;      /* 字形点阵字节数 */
    uint16_t offset;    /* 在 font_xx_bitmap[] 数组中的起始字节偏移 */
} font_16_glyph_t;

查找单个字符时，font_16_find(uint16_t codepoint) 对升序表执行 O(log N) 二分查找（278 个字形最多比较 9 次即可命中）：

const font_16_glyph_t *g = font_16_find(0x8377U); /* 查找 '荷' */
if (g != NULL)
{
    const uint8_t *bits = font_16_bitmap + g->offset;
    /* 使用 g->width, FONT_16_HEIGHT (16), g->size 进行光栅化 */
}

对于仅含 12 个字符（0123456789.-）的主读数字库 font_num_40，则直接通过 font_num_40_index(char ch) 映射为 0..11 的常数下标，实现 O(1) 零开销寻址。

多语言运行时切换与缺字安全回退

固件支持简体中文（0）、英文（1）、台湾繁体中文（2）三语实时切换：

1. ASCII 与 ± 共享主字库：繁体字库 font_16_tw 和 font_24_tw 仅存储繁体汉字点阵；绘制繁体字符串遇到 ASCII 字母、数字或 ± 时，自动回落到 font_16 / font_24 查找，避免重复存储西文字形。
2. 整句缺字检查与回退保护：返回繁体 UI 文案前，渲染层会先扫描该 UTF-8 字符串中的每个汉字是否均存在于对应繁体字库中；一旦发现任一字符未收录，整条文案自动回退为对应的简体中文字符串，避免屏幕上出现空白方框或乱码。
3. 固定边界防溢出：英文标签使用紧凑缩写（如 PEAK、TRACK），与中繁文案共用同一套行高和列边界，切换语言时无需重算菜单布局坐标。

在 RGB565 条带画布中光栅化 1-bit 字形

在 240×8 的条带渲染架构下，字形绘制函数 AppUi_DrawGlyphBits() 只光栅化当前条带 [stripY, stripY + 7] 与字形外框 [glyphY, glyphY + glyphH - 1] 相交的那几行：

static void AppUi_DrawGlyphBits(int16_t x, int16_t y,
                                uint8_t width, uint8_t height,
                                const uint8_t *bits, uint16_t color)
{
    uint8_t stride = (uint8_t)((width + 7U) >> 3U);
    uint8_t row;
    uint8_t col;

    for (row = 0U; row < height; row++)
    {
        int16_t drawY = (int16_t)(y + (int16_t)row);

        /* 仅处理落在当前 8 行条带内的扫描行 */
        if ((drawY < (int16_t)appUiCanvas.y) ||
            (drawY >= (int16_t)(appUiCanvas.y + appUiCanvas.height)))
        {
            continue;
        }

        const uint8_t *rowBits = bits + ((uint16_t)row * stride);
        uint16_t *dstRow = &appUiCanvas.pixels[(uint16_t)(drawY - (int16_t)appUiCanvas.y) * 240U];

        for (col = 0U; col < width; col++)
        {
            int16_t drawX = (int16_t)(x + (int16_t)col);
            if ((drawX >= 0) && (drawX < 240))
            {
                if ((rowBits[col >> 3U] & (uint8_t)(0x80U >> (col & 7U))) != 0U)
                {
                    dstRow[drawX] = color;
                }
            }
        }
    }
}

Unicode 二分查找与字形索引检索

子集化字库按 Unicode 码点升序存储。在嵌入式 C 端，使用二分查找在 O(log N) 时间内完成字形定位：

/* Unicode 升序索引表二分查找字形偏移 */
int32_t Font_FindGlyphIndex(const uint16_t *unicodeTable, uint16_t count, uint16_t codePoint)
{
    int32_t low = 0;
    int32_t high = (int32_t)count - 1;

    while (low <= high)
    {
        int32_t mid = low + ((high - low) >> 1);
        if (unicodeTable[mid] == codePoint)
        {
            return mid; /* 命中字形偏移索引 */
        }
        else if (unicodeTable[mid] < codePoint)
        {
            low = mid + 1;
        }
        else
        {
            high = mid - 1;
        }
    }
    return -1; /* 未收录字符，触发缺字回退 */
}

自动化字库提取与代码生成脚本

通过标准 Python 脚本解析 BDF/TTF 字体，提取文案涉及的字符并生成 C99 数组：

# bdf_subset_generator.py (轻量生成流水线核心实现)
def bdf_glyph_to_c_bytes(hex_lines, width, height):
    stride = (width + 7) // 8
    c_bytes = []
    for line in hex_lines:
        row_val = int(line, 16)
        # 按 stride 拆分字节，高位在左 (MSB leftmost)
        for i in range(stride - 1, -1, -1):
            c_bytes.append((row_val >> (i * 8)) & 0xFF)
    return c_bytes

def generate_font_c_file(chars, bdf_dict, font_name, width, height):
    # 1. 按 Unicode 码点严格升序排序
    sorted_chars = sorted(list(set(chars)), key=lambda c: ord(c))
    stride = (width + 7) // 8
    print(f"/* 自动生成的 {font_name} 1-bit 点阵字库 */")
    print(f"const uint16_t {font_name}_Index[{len(sorted_chars)}] = {{")
    print("    " + ", ".join(f"0x{ord(c):04X}" for c in sorted_chars))
    print("};")
    print(f"const uint8_t {font_name}_Bitmaps[{len(sorted_chars)} * {stride * height}] = {{")
    for c in sorted_chars:
        bytes_list = bdf_glyph_to_c_bytes(bdf_dict[c], width, height)
        hex_str = ", ".join(f"0x{b:02X}" for b in bytes_list)
        print(f"    /* '{c}' U+{ord(c):04X} */ {hex_str},")
    print("};")

生成后的工程核查要点：

• 确认新增字符已全部收录在升序索引表中，且生成器无字符越界或缺字报警。
• 检查字模预览图，确认极小字号繁体字无笔画重叠粘连，且西文与中文字符基线对齐一致。
• 固件支持整句缺字回退保护机制，当目标语言字库缺失任一汉字时安全降级，避免屏幕显示乱码或空白块。

运行环境与现有问题

硬件与资源基线

固件运行于裸机环境，SysTick 提供 1 ms 基础时基，主循环通过协作式大循环（Super-Loop）轮询调度各业务与驱动模块：

• Flash (ROM) / SRAM：典型配置如 512 KB Flash / 144 KB SRAM，全程禁止动态堆内存分配；
• 显示通路：240×320 彩屏，采用 8 行条带局部画布（3.84 KB RAM）结合 SPI DMA 异步传输；
• 硬实时传感器：高精度 ADC 运行于 SPI DMA + 外部引脚中断（高抢占优先级）。

常见架构痛点

1. UI 逻辑过载与巨石文件：单文件容易达到数千行，页面跳转、测量主页、设置子页、参数校准、字库光栅化与绘图流水线深度耦合，难以维护与独立测试。
2. 主循环周期无序抖动（Cycle Jitter）：main.c 的 while(1) 平铺串行调用所有模块的 Process()，缺乏执行周期分频与时间片预算。慢速任务（如存储操作或复杂运算）瞬时拉长单圈耗时，导致 1 ms 按键消抖状态机产生迟滞。
3. 外部 NOR Flash 物理擦写阻塞风险：SPI Flash 扇区擦除耗时数十至数百毫秒，若在主循环中同步等待 BUSY，会挤压传感器数据消费与看门狗喂狗窗口。
4. 模块间隐式耦合与硬编码菜单：各业务模块通过跨层读写全局结构体交互；UI 菜单项的坐标、高亮、步进加减全部硬编码计算，新增参数项需要改动多处绘图代码。

重构设计目标

• 行为兼容：保持既有测量逻辑、按键交互手感与存储二进制格式；
• 零动态内存：全程禁止 malloc/free，所有新增队列、路由表与配置表均驻留静态 SRAM 或 const Flash；
• 耗时目标：主循环常见单圈耗时控制在 < 2 ms，减少按键响应抖动，具体耗时需上板测量；
• 职责拆分：将绘图、页面切换和业务处理拆开，通过接口交互。

模块划分

+-------------------------------------------------------------------------+
|                    分频节拍调度器 (main.c / Sched_Run)                   |
|  [1 ms 硬实时]     [10 ms 测控解算]    [100 ms 低频状态]   [Idle 分片]  |
|  按键扫描/消抖     AD7190队列/峰值判定  电池ADC/方向/时钟   UI条带/Flash |
+--------+-------------------+-------------------+----------------+-------+
         |                   |                   |                |
         v                   v                   v                |
+------------------------------------------------------------+    |
|          静态无锁环形事件总线 (app_event / Ring Buffer)      |    |
|    生产者: 按键单击/长按、超载报警、记录保存完成、标定事件     |    |
+----------------------------+-------------------------------+    |
                             | AppEvent_Poll                      |
                             v                                    v
+-------------------------------------------------------------------------+
|                     UI 子系统解耦与表驱动渲染管线                         |
|  app_ui_router (顶层页面路由 + 顶栏/底栏公共区绘制)                      |
|    ├─► app_ui_page_main   (测量主页: 40px 读数 + 动态量程波形)           |
|    ├─► app_ui_page_menu   (通用表驱动菜单引擎 + Flash const 配置表)      |
|    ├─► app_ui_page_calib  (传感器六点标定向导)                           |
|    └─► app_ui_page_record (测试记录分页浏览与单条/整表删除)              |
|                             │                                           |
|                             ▼                                           |
|  app_ui_engine (240×8 条带裁剪画布 + 字库光栅化 + 基础图元)               |
+-------------------------------------------------------------------------+

一、按周期调度主循环任务

四级任务时间片模型

将平铺在 main() 中的约 20 个 Process() 按实时性敏感度划分为 4 个等级：

用无符号差值判断周期

用 uint32_t 无符号差值判断周期，可以处理毫秒计数器约 49.7 天后的回绕。这里要求两次检查之间不跨过完整的计数周期；分频本身不能消除任务执行造成的延迟：

static void Sched_Run(void)
{
    uint32_t currentTick = PlatformTime_GetMs();

    /* Level 0: 1 ms 高频输入检测 */
    if ((uint32_t)(currentTick - s_lastTick1ms) >= 1U)
    {
        s_lastTick1ms = currentTick;
        AppButtons_Process();
        AppController_Process();
    }

    /* Level 1: 10 ms 测控解算与报警节拍 */
    if ((uint32_t)(currentTick - s_lastTick10ms) >= 10U)
    {
        s_lastTick10ms = currentTick;
        AppAd7190_Process();
        AppTest_Process();
        Buzzer_Process();
    }

    /* Level 2: 100 ms 慢速状态采集 */
    if ((uint32_t)(currentTick - s_lastTick100ms) >= 100U)
    {
        s_lastTick100ms = currentTick;
        BatteryAdc_Process();
        DirAdc_Process();
        AppState_Process();
    }

    /* Level 3: 非阻塞背景分片推进（LCD 条带 DMA 收尾/提交 + Flash 状态轮询） */
    LcdSt7789_Process();
    AppUi_Process();
    AppRecordStore_Process();

    /* 主循环唯一安全喂狗点 */
    Iwdg_Feed();
}

交互式在线演示：四级分频协作调度器与无锁环形总线

下面的演示按 1 ms、10 ms、100 ms 推进任务，并在空闲时刷新条带。点击按键或超载按钮可以向队列投递事件，再单步观察任务执行和事件消费。演示用于说明调度顺序，不代表实板耗时。

二、拆分 UI 文件和页面接口

模块职责切分

将巨石 UI 模块按“渲染引擎 + 页面路由 + 独立业务页”拆分为分层子系统：

页面生命周期契约（UiPageInterface）

为消除页面与路由器之间的双向循环依赖，所有业务页面统一实现如下函数指针表：

typedef struct
{
    void (*OnEnter)(void);                                      /* 进入页面时初始化局部状态 */
    bool (*OnEvent)(const AppEvent *event);                     /* 处理按键/系统事件，返回 true 表示已消费 */
    void (*OnDrawStrip)(uint16_t stripY, uint16_t stripHeight); /* 绘制当前 8 行条带内的页面内容 */
    void (*OnExit)(void);                                       /* 离开页面时清理或触发保存 */
} UiPageInterface;

顶层路由器调度页面切换与事件分发，并内置“跨页物理释放锁存（Wait-Release Latch）”，防止长按切页误触发新页面的长按操作：

static const UiPageInterface *s_currentPage = NULL;
static bool s_waitReleaseLatch = false;

void UiRouter_Switch(const UiPageInterface *newPage)
{
    if ((newPage == NULL) || (newPage == s_currentPage))
    {
        return;
    }
    if (s_currentPage != NULL && s_currentPage->OnExit != NULL)
    {
        s_currentPage->OnExit();
    }
    s_currentPage = newPage;
    /* 跨页防误触锁存：切页后必须等待所有物理按键松开，才允许新页面响应下一次按键 */
    s_waitReleaseLatch = true;
    if (s_currentPage->OnEnter != NULL)
    {
        s_currentPage->OnEnter();
    }
}

当条带渲染管线遍历 40 个条带（stripY 从 0 到 312，步进 8）时，由 ui_router 统一编排：

1. 绘制全局公共顶部状态栏（y ∈ [0, 23]）；
2. 调用当前活动页面的 OnDrawStrip(stripY, 8) 绘制中部业务区；
3. 绘制全局公共底部操作提示栏（y ∈ [296, 319]）。

三、用只读表描述菜单

用 const MenuItemConfig 表描述菜单项并放入 Flash，由通用渲染器计算坐标和反色框，减少逐项手写的重复代码：

typedef enum
{
    MENU_TYPE_SUBPAGE = 0,   /* 子菜单跳转入口 */
    MENU_TYPE_INT_RANGE,     /* 整数范围步进调节（如背光亮度、归零时间） */
    MENU_TYPE_ENUM_CYCLE,    /* 枚举列表循环切换（如单位、测试模式、语言） */
    MENU_TYPE_ACTION_CONFIRM /* 动作二次确认弹窗（如恢复默认设置） */
} MenuItemType;

typedef struct
{
    const char   *label;           /* 菜单项标签（或三语词条 ID） */
    MenuItemType  type;            /* 控件类型 */
    void         *boundValue;      /* 绑定的设置变量指针 */
    int32_t       minValue;        /* 最小值 */
    int32_t       maxValue;        /* 最大值 */
    int32_t       stepValue;       /* 步进值 */
    const char  **enumDisplayList; /* 枚举显示文本表 */
    void        (*onChanged)(void);/* 修改即时生效回调 */
} MenuItemConfig;

新增或调整一个菜单项只需在 const MenuItemConfig[] 数组中添加一行声明；通用的菜单页面渲染器负责焦点移动、视口滚动、编辑态反色高亮、数值边界夹紧与退出保存：

void Menu_DrawStrip(const MenuItemConfig *items, uint8_t count, uint8_t focusIndex,
                    uint16_t stripY, uint16_t stripHeight)
{
    for (uint8_t i = 0; i < count; i++)
    {
        int16_t itemY = (int16_t)(MENU_TOP_OFFSET + i * MENU_ITEM_HEIGHT);
        /* 条带裁剪：仅当菜单项垂直区间落在当前条带内时才执行绘制 */
        if ((itemY + MENU_ITEM_HEIGHT <= (int16_t)stripY) ||
            (itemY >= (int16_t)(stripY + stripHeight)))
        {
            continue;
        }
        bool isFocus = (i == focusIndex);
        /* 在条带画布中渲染菜单文本、反色高亮框与当前绑定数值 */
        Canvas_DrawMenuItem(items[i].label, itemY, isFocus);
    }
}

四、用静态队列传递事件

为避免按键、采样报警、存储完成等模块直接跨层修改 UI 状态，在 SRAM 中开辟固定 16 槽位的环形事件队列：

typedef enum
{
    EVT_NONE = 0,
    EVT_KEY_CLICK,       /* 参数: KeyID */
    EVT_KEY_LONG_PRESS,  /* 参数: KeyID */
    EVT_KEY_RELEASE_ALL, /* 全部按键物理松开 */
    EVT_DATA_ALARM,      /* 参数: 告警方向与数值 */
    EVT_RECORD_SAVED,    /* 参数: 记录槽位或状态码 */
    EVT_BATTERY_LOW,     /* 参数: 剩余电量百分比 */
    EVT_CALIB_DONE       /* 参数: 标定结果状态码 */
} AppEventId;

typedef struct
{
    AppEventId id;
    uint16_t   param1;
    uint32_t   param2;
} AppEvent;

完整的环形队列收发逻辑如下，实现生产者与消费者的零动态内存解耦：

#define EVENT_QUEUE_CAPACITY (16U)

typedef struct
{
    AppEvent buffer[EVENT_QUEUE_CAPACITY];
    uint8_t  head;
    uint8_t  tail;
    uint8_t  count;
} EventQueue;

static EventQueue s_eventQueue;

bool AppEvent_Post(AppEventId id, uint16_t param1, uint32_t param2)
{
    if (s_eventQueue.count >= EVENT_QUEUE_CAPACITY)
    {
        return false; /* 队列满，丢弃并报警 */
    }
    s_eventQueue.buffer[s_eventQueue.tail].id = id;
    s_eventQueue.buffer[s_eventQueue.tail].param1 = param1;
    s_eventQueue.buffer[s_eventQueue.tail].param2 = param2;
    s_eventQueue.tail = (uint8_t)((s_eventQueue.tail + 1U) % EVENT_QUEUE_CAPACITY);
    s_eventQueue.count++;
    return true;
}

bool AppEvent_Poll(AppEvent *outEvent)
{
    if ((s_eventQueue.count == 0U) || (outEvent == NULL))
    {
        return false;
    }
    *outEvent = s_eventQueue.buffer[s_eventQueue.head];
    s_eventQueue.head = (uint8_t)((s_eventQueue.head + 1U) % EVENT_QUEUE_CAPACITY);
    s_eventQueue.count--;
    return true;
}

• 发布方（Producers）：按键模块识别到短按/长按、测控模块识别到超载或完成快照时，仅调用 AppEvent_Post() 向队列压入事件；
• 消费方（Dispatcher）：UiRouter_Process() 每轮从队列头取出一个事件，优先交给当前活动页面的 OnEvent() 处理；若当前页面未消费，再由顶层路由器兜底处理全局事件（如超载提示或低电告警）。

风险防控与工程验收准则

每次合入重构改动前，检查以下事项：

• 编译与内存审计：编译器全量构建达到 0 Error，核对 .map 文件中 Code + RO-data 与 RW + ZI 增量符合预算。
• 时序确定性验证：在开启高频传感器连续采样（如 2 kHz+）、LCD 连续翻页刷新与外部 Flash 后台扇区擦除并发条件下，按键短按/长按响应无粘滞，看门狗无复位，采样队列无溢出（overrun == 0）。
• 前端演示同步：涉及可见 UI 布局或交互规则变更时，同步更新网页交互模拟器并运行自检脚本。

芯片特性与驱动概览

M24C02 是 2 Kbit（256 × 8 bit）串行 I2C EEPROM，内部按 16 页 × 16 字节组织，支持标准模式 100 kHz 与快速模式 400 kHz。当前固件驱动配置如下：

硬件连接与器件地址编码

引脚与开漏配置

本板使用 I2C3 默认映射（I2C3_RMP = 00），无需调用重映射函数：

M24C02（SO8 封装）的 E0/E1/E2 为硬件地址脚，WC 为写保护脚（低电平允许写入，高电平禁止写入）。若 WC 被拉高，写操作会在内部写周期或数据阶段失败。

器件选择字节（Device Select Byte）

Bit:   7   6   5   4   3   2   1   0
     +---+---+---+---+---+---+---+---+
     | 1 | 0 | 1 | 0 | E2| E1| E0|R/W|
     +---+---+---+---+---+---+---+---+

• 高 4 位固定为 1010；
• E2/E1/E0 由硬件引脚电平决定，本板实测 7 位地址为 0x50（对应 E2=0, E1=0, E0=0）；
• R/W = 0 为写（0xA0），R/W = 1 为读（0xA1）。

驱动中将 7 位地址左移 1 位后传给标准外设库 I2C_SendAddr7bit()：

#define M24C02_ADDRESS_BYTE ((uint8_t)(M24C02_I2C_ADDRESS << 1U))

存储组织与 16 字节页回绕陷阱

M24C02 共有 16 页，每页 16 字节，页起始地址依次为 0x00, 0x10, 0x20 ... 0xF0。

页写回绕规则（Page Wrap-around）：数据手册规定，在单次 Page Write 事务中，每写入一字节，芯片内部字地址仅低 4 位自动加 1，高 4 位页号保持不变。如果一次连续写入跨越了 16 字节页尾（例如从 0x0E 连续写 4 字节），第 3、4 字节不会进入下一页的 0x10, 0x11，而是回绕覆盖本页开头的 0x00, 0x01！

因此，M24c02_Write() 在驱动层实现了严格的页边界自动拆分：

当 length > 0：
  本页剩余空间 pageRemain = 16 - (address % 16)
  本次写入长度 chunkLen   = min(length, pageRemain)
  执行单页写入 M24c02_WritePage(address, data, chunkLen)
  执行 ACK 轮询等待内部写周期 tWR 完成（最长 10 ms）
  address += chunkLen
  data    += chunkLen
  length  -= chunkLen

例如从 0x0E 写 4 字节时，驱动自动拆成两笔独立事务：第一笔写 0x0E..0x0F（2 字节）并等待编程完成；第二笔再写 0x10..0x11（2 字节）并等待编程完成，避免页内回绕覆盖。

交互式在线演示：16 字节页回绕陷阱与 A/B 双槽乒乓存储

下面用 256 字节模拟 EEPROM。试着从 0x0E 写入 4 字节，对比分页与不分页的结果；再切换到 A/B 双槽，观察更新中断后会保留哪一份参数。点击单元格可以查看所属页和槽位。

I2C 事务帧格式与 ACK 轮询

随机读单字节

当前 M24c02_Read() 对每个字节采用确定性的随机读时序（在最后 1 字节接收前关闭 ACK 并产生 STOP）：

START
  → 发送 0xA0（写器件地址），等待 ADDRF
  → 发送 8 位字地址 word_address，等待 BYTEF
RESTART
  → 关闭 ACK 使能
  → 发送 0xA1（读器件地址），等待 ADDRF
  → 读 STS1 + 读 STS2 清 ADDRF，立即置位 STOP
  → 等待 RXDATNE，读取 1 字节数据
  → 等待 I2C BUSY = 0，重新打开 ACK 使能

页写与内部写周期 ACK 轮询（ACK Polling）

发出页写数据的最后一个字节并产生 STOP 后，M24C02 进入最长 5 ms 的内部非易失性擦写周期（tWR）。在此期间，芯片不会响应外部访问，对器件选择字节会返回 NACK。

驱动不采用固定 Delay(5) 盲等，而是通过 M24c02_WaitWriteComplete() 执行 ACK 轮询，一旦芯片提前写完即可立即返回：

等待 I2C BUSY = 0
循环（以 PlatformTime_GetMs() 无符号差值计时，上限 10 ms）：
  发出 START
  发送 0xA0（写器件地址）
  轮询 STS1：
    - 若 ADDRF = 1（从机已回 ACK，内部写完成）：
        读 STS1/STS2 清 ADDRF → 发 STOP → 等 BUSY = 0 → 返回 OK
    - 若 ACKFAIL = 1（从机仍忙，回 NACK）：
        清 ACKFAIL 标志 → 发 STOP → 等 BUSY = 0 → 继续下一轮尝试
若超过 10 ms 仍未收到 ACK → 返回 M24C02_STATUS_TIMEOUT

M24c02_Init() 同样复用该函数探测器件是否在线应答。

N32G455 I2C3 外设配置与错误恢复

时钟与寄存器特性

I2C3 挂载于 APB2 总线（PCLK2 = 64 MHz）。调用标准外设库 I2C_Init() 配置 100 kHz 时：

• CLKCTRL (CCR) 计算值为 64 MHz / (100 kHz × 2) = 320，实际产生标准 100 kHz SCL；
• 库函数将大于 36 MHz 的 CTRL2.FREQ 封顶记为 36，TMRISE 设为 37。实际波形上升时间受板级外部上拉电阻与走线电容支配，联调时应以示波器实测为准。

外设异常自恢复（M24c02_RecoverPeripheral）

I2C 总线在受到静电、毛刺或从机异常影响时，容易卡在 BUSY 或仲裁错误状态。驱动在任何读写或初始化超时/错误退出前，均自动调用 M24c02_RecoverPeripheral()：

1. 置位 STOP 请求并重新打开 ACK 配置；
2. 清除 TIMOUT、OVERRUN、ARLOST、BUSERR、ACKFAIL 全部错误标志；
3. 置位并释放 I2C3 软件复位位（SWRST），最后执行 I2C_DeInit(I2C3) 并按 100 kHz 重新初始化寄存器。

公开接口与最小调用示例

接口定义与状态码

typedef enum
{
    M24C02_STATUS_OK = 0,
    M24C02_STATUS_INVALID_PARAM, /* 空指针、长度为 0，或 address + length > 256 */
    M24C02_STATUS_TIMEOUT,       /* 10 ms 内标志未就绪或内部写周期未完成 */
    M24C02_STATUS_NACK,          /* 地址或数据阶段收到 NACK */
    M24C02_STATUS_BUS_ERROR      /* 总线错误、仲裁丢失、溢出等 */
} m24c02_status_t;

m24c02_status_t M24c02_Init(void);
m24c02_status_t M24c02_Read(uint16_t address, uint8_t *data, uint16_t length);
m24c02_status_t M24c02_Write(uint16_t address, const uint8_t *data, uint16_t length);

最小调用示例

#include "drv_m24c02.h"

static void Eeprom_Demo(void)
{
    /* 选取跨越 0x0F -> 0x10 页边界的 4 字节测试跨页拆分 */
    uint8_t tx[4] = { 0x10U, 0x32U, 0x54U, 0x76U };
    uint8_t rx[4] = { 0U };

    if (M24c02_Init() != M24C02_STATUS_OK)
    {
        return;
    }

    if (M24c02_Write(0x0EU, tx, sizeof(tx)) != M24C02_STATUS_OK)
    {
        return;
    }

    (void)M24c02_Read(0x0EU, rx, sizeof(rx));
}

与上层 A/B 双槽掉电安全参数存储的协同

驱动层只负责可靠的字节数组读写，不感知具体业务数据结构。上层参数管理模块将 M24C02 的 256 字节空间对半划分为两个 128 字节的乒乓备份槽位：

A/B 双槽结构体定义与完整 C99 实现

#include <string.h>

#define PARAM_SLOT_SIZE (128U)
#define PARAM_MAGIC     (0x5041524DU) /* 'PARM' ASCII 魔数 */

#pragma pack(push, 1)
typedef struct
{
    uint32_t magic;          /* 4B: 魔数标识 */
    uint16_t version;        /* 2B: 参数结构版本号 */
    uint32_t sequence;       /* 4B: 单调递增序号，越大表示版本越新 */
    uint8_t  payload[116];   /* 116B: 业务配置与标定曲线参数 */
    uint16_t crc16;          /* 2B: CRC-16/MODBUS 校验码 (覆盖偏移 0..125) */
} ParamSlot;
#pragma pack(pop)

/* 上电扫描：校验 A/B 两槽，自动选择版本最新且无损的镜像恢复 */
bool ParamStore_Load(ParamSlot *outParams, bool *outActiveIsSlotA)
{
    ParamSlot slotA, slotB;
    bool validA = false;
    bool validB = false;

    if (M24c02_Read(0x00, (uint8_t *)&slotA, sizeof(ParamSlot)) == M24C02_STATUS_OK)
    {
        validA = (slotA.magic == PARAM_MAGIC) &&
                 (slotA.crc16 == Crc16_Modbus((const uint8_t *)&slotA, sizeof(ParamSlot) - 2));
    }

    if (M24c02_Read(0x80, (uint8_t *)&slotB, sizeof(ParamSlot)) == M24C02_STATUS_OK)
    {
        validB = (slotB.magic == PARAM_MAGIC) &&
                 (slotB.crc16 == Crc16_Modbus((const uint8_t *)&slotB, sizeof(ParamSlot) - 2));
    }

    if (validA && validB)
    {
        /* 两个槽位均完整有效，选用序号较大（较新）的槽 */
        if (slotA.sequence >= slotB.sequence)
        {
            *outParams = slotA;
            if (outActiveIsSlotA) *outActiveIsSlotA = true;
        }
        else
        {
            *outParams = slotB;
            if (outActiveIsSlotA) *outActiveIsSlotA = false;
        }
        return true;
    }
    else if (validA)
    {
        *outParams = slotA;
        if (outActiveIsSlotA) *outActiveIsSlotA = true;
        return true;
    }
    else if (validB)
    {
        *outParams = slotB;
        if (outActiveIsSlotA) *outActiveIsSlotA = false;
        return true;
    }

    return false; /* 两槽均损坏（初次上电或硬件故障），应写入出厂默认值 */
}

/* 掉电安全写入：始终写入非活动槽，并整槽读回校验 */
bool ParamStore_Save(const ParamSlot *inParams, bool currentIsSlotA)
{
    uint16_t targetAddr = currentIsSlotA ? 0x80 : 0x00; /* 写入交替备用槽 */
    ParamSlot newSlot = *inParams;
    newSlot.magic = PARAM_MAGIC;
    newSlot.sequence++;
    newSlot.crc16 = Crc16_Modbus((const uint8_t *)&newSlot, sizeof(ParamSlot) - 2);

    /* 1. 跨 8 页写入目标槽 */
    if (M24c02_Write(targetAddr, (const uint8_t *)&newSlot, sizeof(ParamSlot)) != M24C02_STATUS_OK)
    {
        return false;
    }

    /* 2. 写后整槽读回逐字节校验，确保物理无损 */
    ParamSlot readback;
    if (M24c02_Read(targetAddr, (uint8_t *)&readback, sizeof(ParamSlot)) != M24C02_STATUS_OK)
    {
        return false;
    }

    return (memcmp(&newSlot, &readback, sizeof(ParamSlot)) == 0);
}

这样设计的工程价值在于：

1. 掉电原子性：即使在 M24c02_Write() 跨 8 页（128 B）写入中途发生断电，被破坏的也只是正在写入的新槽；下次上电时，AppParam_Load() 校验两个槽的 CRC-16 与递增序号，自动回退到完好无损的旧槽镜像。
2. 写后读回校验：每次写入非活动槽后，上层立即调用 M24c02_Read() 整槽读回并逐字节比对，确认物理存储无误后才更新活动槽指针。
3. 看门狗安全边界：写满 128 字节共 8 页，正常耗时约 8 × 5 ms ≈ 40 ms（极端超时上界 < 100 ms），远小于约 1 s 的独立看门狗窗口。

移植检查清单

• 引脚与重映射：确认目标板 SCL/SDA 引脚与 I2C3_RMP 配置，GPIO 设为复用开漏（GPIO_Mode_AF_OD）。
• 电气与写保护：确认外部上拉电阻已焊接、WC 脚拉低允许写入、VCC 与 MCU I2C 电平一致。
• 跨页边界测试：向 0x0F 地址连续写入 2 字节以上，读回确认 0x0F 与 0x10 均正确，且本页首地址 0x00 未被回绕篡改。
• 调用上下文约束：仅在初始化与主循环中调用，严禁在中断服务程序（ISR）中调用阻塞式 I2C 读写。

芯片特性与驱动概览

W25Q128 是 Winbond 128 Mbit（16 MiB）标准 SPI NOR Flash，期望 24 位 JEDEC ID 为 0xEF4018（0xEF 代表 Winbond，0x40 代表存储器类型，0x18 代表 128 Mbit 容量）。

硬件连接与 SPI3 重映射

引脚分配

本板通过 GPIO_RMP3_SPI3（即 AFIO_RMP_CFG3 的 SPI3_RMP = 11）将 SPI3 重映射至 PC3 / PA0 / PA1，片选 /CS 由 PA2 软件控制：

初始化时钟与重映射代码如下：

RCC_EnableAPB2PeriphClk(RCC_APB2_PERIPH_AFIO |
                        RCC_APB2_PERIPH_GPIOA |
                        RCC_APB2_PERIPH_GPIOC, ENABLE);
RCC_EnableAPB1PeriphClk(RCC_APB1_PERIPH_SPI3, ENABLE);
GPIO_ConfigPinRemap(GPIO_RMP3_SPI3, ENABLE);

全双工单字节收发规则

SPI3 工作在双线全双工模式，即使只向 Flash 发送命令或地址，MISO 也会同步移入字节。每次写入 SPI_DAT 后必须等待 RNE (RXNE) 并读走 SPI_DAT，否则下一字节会触发 OVR（接收溢出）；整段命令或数据结束后，必须等待 BUSY 标志清零才能拉高 PA2 (/CS)。

存储组织与 NOR Flash 物理写入规则

读写时需要注意三个限制：

1. 先擦后写（只允许 1 → 0）：扇区擦除后所有位变为 1（字节为 0xFF），页编程只能把 1 改写为 0；若要把 0 变回 1，必须先擦除整个 4 KiB 扇区。驱动层 W25q128_Write() 不会隐式替调用方擦除扇区。
2. 256 字节页回绕边界：单次 Page Program (0x02) 若跨越 256 字节页尾（address & 0xFF 溢出），芯片内部地址会回绕覆盖当前页首部。因此 W25q128_Write() 每次计算 pageRemain = 256 - (address & 255)，在页边界处自动拆分为多笔页编程事务。
3. 4 KiB 扇区对齐检查：扇区擦除传入的 address 若不满足 (address & 0xFFFU) == 0，驱动直接返回 W25Q128_STATUS_INVALID_PARAM，防止误擦除相邻数据。

已实现命令与状态寄存器保护核查

命令列表

状态寄存器与写保护检查

状态寄存器 1（SR1，0x05）的核心位定义如下：

每次发送 Write Enable (0x06) 后，驱动都会立即读回 SR1 校验 WEL == 1；若 WEL 未置位，立即返回 W25Q128_STATUS_WRITE_ENABLE_FAILED。

此外，上层记录存储服务在挂载前会调用 W25q128_ReadStatusRegisters() 同时读取 SR1、SR2、SR3，保守要求：

• SR1 的 BP[2:0] == 0；
• SR2 的 CMP == 0；
• SR3 的 WPS == 0。

任一保护位非零时拒绝写入，且驱动绝不主动下发改写状态寄存器的指令，防止意外将 Flash 锁成只读状态。

为什么需要非阻塞页编程与扇区擦除

在开启独立看门狗（窗口约 1 s）和 AD7190 高频连续采样后，一次 4 KiB 扇区擦除在物理上需要 45～400 ms（实测约 88 ms）。如果主循环直接调用阻塞式 W25q128_SectorErase() 原地死等 BUSY == 0，会导致：

• 主循环停摆近百毫秒，按键消抖掉帧、LCD 8 行条带刷新卡顿；
• AD7190 的 255 帧环形队列可能逼近高水位；
• 连续擦除多个扇区时直接触发看门狗复位。

一次擦写包含两个阶段：

• SPI 命令下发阶段：发送 0x06 + 0x20 + 3 字节地址仅占几个微秒；即使是 256 字节满页编程，在 8 MHz SCLK 下线上数据传输也仅需 约 0.256 ms；
• 芯片内部电荷擦写阶段：拉高 /CS 后，Flash 内部高压泵独自工作数毫秒至数百毫秒，此时完全不需要占用 MCU。

因此驱动提供了一组单事务非阻塞接口：

w25q128_status_t W25q128_PageProgramStart(uint32_t address, const uint8_t *data, uint16_t length);
w25q128_status_t W25q128_SectorEraseStart(uint32_t address);
w25q128_status_t W25q128_ReadBusy(bool *busy);
w25q128_status_t W25q128_PollOperation(bool *completed);
bool             W25q128_IsOperationActive(void);

非阻塞状态推进流程如下：

1. 调用 Start 接口（PageProgramStart 或 SectorEraseStart）：
   ├─ 校验地址、单页不跨界或 4 KiB 扇区对齐
   ├─ 若驱动已有活动事务，或单次读 SR1 发现硬件 BUSY=1 → 立即返回 W25Q128_STATUS_BUSY
   ├─ 发送 0x06 并确认 WEL = 1
   ├─ 记录活动事务上下文与起始时间戳（100 ms / 1000 ms 超时）
   └─ 发送 0x02+地址+数据（≤ 0.26 ms）或 0x20+地址，拉高 CS 后立即返回主循环

2. 主循环每轮调用 W25q128_PollOperation(&completed)：
   ├─ 发送一次 0x05 读取 1 字节 SR1（耗时仅数微秒）
   ├─ 若 BUSY == 0：清除活动事务标志，置 *completed = true，返回 OK
   ├─ 若 BUSY == 1 且未超时：置 *completed = false，立即返回 OK 让主循环继续运行
   └─ 若 BUSY == 1 且超出截止时间：返回 TIMEOUT，但保持事务隔离直到物理 BUSY 真正清零

在非阻塞事务活动期间（W25q128_IsOperationActive() == true），任何普通 Read、重复 Start 或同步擦写都会被驱动拦截并返回 W25Q128_STATUS_BUSY，避免同一执行上下文中的事务交叉。

最小探测与读写自检示例

#include "drv_w25q128.h"

/* 1. 启动阶段探测 JEDEC ID */
static w25q128_status_t Flash_Probe(void)
{
    uint32_t jedecId = 0U;
    w25q128_status_t status;

    status = W25q128_Init();
    if (status != W25Q128_STATUS_OK)
    {
        return status;
    }

    status = W25q128_ReadJedecId(&jedecId);
    if (status != W25Q128_STATUS_OK)
    {
        return status;
    }

    return (jedecId == W25Q128_JEDEC_ID) ? W25Q128_STATUS_OK
                                         : W25Q128_STATUS_ID_MISMATCH;
}

/* 2. 主循环中推进非阻塞扇区擦除 */
static void Flash_NonBlockingEraseExample(uint32_t sectorAddr)
{
    bool completed = false;

    if (!W25q128_IsOperationActive())
    {
        (void)W25q128_SectorEraseStart(sectorAddr);
        return;
    }

    if (W25q128_PollOperation(&completed) == W25Q128_STATUS_OK && completed)
    {
        /* 扇区擦除已在后台完成，可安全发起后续页编程或读取 */
    }
}

常见故障排查表

模块特性与适用场景

业务状态和事件增多后，分散的 switch-case 与标志位不便检查。这个组件把状态转移集中放在表中，事件按队列顺序处理：

• 声明式状态转移表：以静态常量表集中描述“当前状态 + 触发事件 → 动作函数 + 下一状态”；
• 内置静态 FIFO 事件队列：队列数组由调用方显式提供，零堆内存分配；
• 空闲自环事件（Loop Event）：当外部事件队列为空时，自动执行当前状态绑定的周期循环事件；
• 有界非阻塞调度：每次调用 StateMachine_Process() 最多消费并执行一个事件，单圈耗时还取决于动作函数是否及时返回；
• 业务上下文解耦：通过 void *userContext 向动作函数传递业务数据，状态机内核不保存任何业务全局变量；
• 初始化期配置自检：在 StateMachine_Init() 阶段自动拦截越界状态、越界事件、重复转移项和缺失的循环转移。

运行模型与调度流程

一条状态转移由四元组构成：

{ 触发事件 event, 当前状态 currentState, 动作函数 action, 下一状态 nextState }

单次 StateMachine_Process() 的执行路径如下：

调用 StateMachine_Process(machine)
  │
  ├─ 1. 检查实例、配置表与当前状态是否有效？
  │      └─ 否 ──► 返回 STATE_MACHINE_PROCESS_INVALID
  │
  ├─ 2. 检查 FIFO 事件队列是否非空？
  │      ├─ 非空 ──► 从队列头部弹出最早到达的外部事件 event
  │      └─ 为空 ──► 取出当前状态对应的循环事件 config->loopEvents[currentState]
  │
  ├─ 3. 按顺序扫描 config->transitions 转移表，匹配 (event, currentState)
  │      ├─ 未找到匹配项 ──► 状态保持不变，返回 STATE_MACHINE_PROCESS_IGNORED
  │      └─ 找到匹配项 ───► (a) 若 action != NULL，调用 action(machine, userContext)
  │                         (b) 将 currentState 更新为 nextState
  │                         (c) 返回 STATE_MACHINE_PROCESS_HANDLED

这里的执行顺序是：动作函数 action() 在 currentState 更新之前执行。因此动作函数内部读取 StateMachine_GetState() 得到的是转移前的源状态；动作函数中通过 StateMachine_PostEvent() 投递的新事件会进入 FIFO 队列尾部，留待后续的 Process() 调用处理，不会在当前调用栈中发生递归重入。

交互式内核演示：状态转移与事件调度

向下面的 8 槽 FIFO 投递事件后，单步执行 StateMachine_Process()，可以看到匹配的转移表行和动作执行顺序。队列为空时，演示会执行当前状态的循环事件。