From 39cb1cba90c1986f9c707ac4ac8a05ea3a68ae70 Mon Sep 17 00:00:00 2001
From: yhf <yhf@face.com>
Date: Tue, 21 Jul 2026 09:46:06 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9ESource=E7=8A=B6?=
 =?UTF-8?q?=E6=80=81=E6=9C=BA=E6=94=B9=E9=80=A0=E4=B8=8E=E8=A7=92=E8=89=B2?=
 =?UTF-8?q?=E5=88=87=E6=8D=A2=E7=BB=B4=E6=8A=A4=E8=AE=A1=E5=88=92=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

详细记录了Source状态机改造的目标、当前进度、目标状态机设计、各模块改造细节、实施顺序和验证清单
---
 ...1-source-state-machine-remediation-plan.md | 121 ++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 docs/2026-07-21-source-state-machine-remediation-plan.md

diff --git a/docs/2026-07-21-source-state-machine-remediation-plan.md b/docs/2026-07-21-source-state-machine-remediation-plan.md
new file mode 100644
index 0000000..43f98d0
--- /dev/null
+++ b/docs/2026-07-21-source-state-machine-remediation-plan.md
@@ -0,0 +1,121 @@
+# Source 状态机改造与角色切换维护计划
+
+## 1. 改造目标
+
+将电源（Source）控制整理为与负载（Sink）类似的独立状态机，但保留两者业务差异：
+
+- 北向协议板只负责角色/CC 线选择、协议设置及周期读取协议板电压电流。
+- 功率板角色、模式、电压、电流、继电器和启停全部由 `chrg_source.c` 管理。
+- 所有 Source 南向寄存器命令统一使用 `chrg_sou_com_batch_submit()`，不再散落调用 `chrg_set_sou_reg()`。
+- Source 不判断带载电流。协议板返回电压有效则进入 `RUNNING`；启动后持续无电压则回到 `WAIT`。
+- 协议、协议电压或协议电流发生变化时，重新进入 `INIT`。
+- Source/Sink 不停机切换时，必须先停止旧角色，确认完成后再初始化新角色。
+
+## 2. 当前已完成的修改
+
+当前工作区已完成第一阶段，尚未形成完整状态机：
+
+1. `apps/chrg/applications/utils/chrg_source.c`
+   - 新增 `chrg_source_init_submit(rt_uint8_t idx, struct chrg_switch_t *pSW)`。
+   - 通过一个批次下发 `REG_ELOAD`、`REG_MODE`、`REG_VOLTAGE_OUT + 1`、`REG_CURRENT_OUT + 1` 和 `REG_WORK = WORK_STOP`。
+2. `apps/chrg/applications/utils/chrg_source.h`
+   - 增加上述函数声明。
+3. `apps/chrg/applications/thread/chrg_roll_nor.c`
+   - Source 协议设置流程进入 `IDX_GET_SOURCE_VC` 后提交南向初始化批次。
+   - 仅当批次提交成功时设置 `source.On_Flag = 1`。
+
+注意：当前仍有旧 Source 路径在 `chrg_north.c`、`chrg_roll_nor.c` 和 `chrg_lcd.c` 中直接调用 `chrg_set_sou_reg()`。在完成后续步骤前，新旧逻辑会同时存在，不能作为最终版本发布。
+
+## 3. 目标状态机
+
+在 `chrg_source.h` 中增加明确的 Source 状态：
+
+```c
+typedef enum {
+    SOURCE_WORK_STOP = 0,
+    SOURCE_WORK_WAIT,
+    SOURCE_WORK_INIT,
+    SOURCE_WORK_START,
+    SOURCE_WORK_RUNNING,
+    SOURCE_WORK_STOPPING,
+    SOURCE_WORK_FAULT
+} source_work_mode_t;
+```
+
+在 `chrg_src_t` 中增加每通道状态及参数快照：`work_mode`、`last_protocol`、`last_voltage`、`last_current`、`zero_volt_count`、`retry_count`。参数快照只能在对应命令确认完成后更新。
+
+状态动作：
+
+| 状态 | 动作 | 后续状态 |
+|---|---|---|
+| `INIT` | 批量设置 Source 角色、模式、电压、电流及继电器，保持停止 | `START` |
+| `START` | 批量下发 `REG_WORK = WORK_START` | `WAIT` |
+| `WAIT` | 北向周期读取协议板 VC | 有电压进入 `RUNNING` |
+| `RUNNING` | 更新 VC；检测协议/电压/电流变化 | 变化进入 `INIT` |
+| `STOPPING` | 批量停止输出、关闭功率板继电器 | `STOP` |
+| `STOP` | 清理使能并断开北向继电器 | 保持 |
+
+建议电压大于 `WORK_MIN_VOLT` 即视为有效。电压为零连续 3 次再由 `RUNNING` 回到 `WAIT`，避免单帧异常造成状态抖动。
+
+## 4. COM 端改造
+
+修改 `chrg_mb_write_sys()`：
+
+- 当目标角色为 Source 且当前未工作时，只设置 `pSW->sub = IDX_SET_SOURCE_CC_SET`，由北向依次完成 CC 和协议设置；协议应答完成后才进入 `SOURCE_WORK_INIT`。
+- 同角色下，比较协议、协议电压、协议电流。任一变化则进入 `SOURCE_WORK_INIT`；相同参数不得重复初始化。
+- 不要在收到 `SYS_REG_ROLE_SWITCH` 时立即覆盖实际角色。应保存 `target_role`，在参数生效时启动切换流程。
+- 切换期间返回 `MB_EX_SLAVE_BUSY`，或者只更新影子参数并等待本次切换完成。
+
+角色切换顺序：
+
+```text
+Source -> Sink: Source STOPPING -> STOP -> 切换角色/继电器 -> Sink INIT
+Sink -> Source: Sink STOP -> 切换角色/继电器 -> 北向 CC/协议 -> Source INIT
+```
+
+禁止 Source 和 Sink 的功率板继电器、工作命令在同一通道同时有效。
+
+## 5. 北向流程改造
+
+精简 `chrg_roll_nor_set()` 的 Source 分支，只保留：
+
+1. `IDX_SET_SOURCE_CC_SET`：设置 CC 线，成功后进入 `IDX_SET_SOURCE_PD`。
+2. `IDX_SET_SOURCE_PD`：设置协议，应答成功后设置 `SOURCE_WORK_INIT`。
+3. `IDX_GET_SOURCE_VC`：读取协议板电压电流。
+
+删除 Source 分支中的 `IDX_SET_SOURCE_ID`、`IDX_SET_SOURCE_CV`、`IDX_SER_SOURCE_VOLT`、`IDX_SER_SOURCE_CURR`、`IDX_SET_SOURCE_WORK` 南向设置动作。校准、控制台和 Sink 分支不在本次范围内。
+
+`chrg_north.c` 只解析 Source VC：更新 `source.vc`、`Now_voltage`、`Now_current`，并根据电压推进 `WAIT/RUNNING`。移除 `chrg_source_standard_output()`、`chrg_source_fast_output()` 和旧的分步停机控制，避免解析函数直接下发南向命令。
+
+## 6. 南向完成确认
+
+`chrg_sou_com_batch_submit()` 返回成功仅表示入队成功，不表示功率板已经执行。需要为每通道增加批次完成序号或完成事件：
+
+- `INIT` 批次全部应答匹配后才能进入 `START`。
+- `START` 应答成功后才能进入 `WAIT`。
+- `STOPPING` 批次完成后才能断开北向继电器和修改实际角色。
+- CRC 错误、寄存器不匹配或超时不得推进状态；达到重试上限后进入 `FAULT`。
+
+## 7. 推荐实施顺序
+
+1. 增加 Source 状态枚举、参数快照及 `chrg_source_work()`。
+2. 将 INIT、START、STOPPING 的南向动作全部迁移到 `chrg_source.c`。
+3. 增加南向批次完成通知，再改为应答驱动状态转换。
+4. 精简北向 Source 子状态，只保留 CC、协议和 VC。
+5. 修改 COM 同角色参数差异及跨角色切换。
+6. 清理 `chrg_lcd.c` 中重复的 Source 启停和角色寄存器写入。
+7. 编译并在硬件验证后删除旧字段和旧函数。
+
+## 8. 验证清单
+
+- Keil 编译 `apps/chrg/chrg.uvprojx`，确认无未定义符号和头文件循环依赖。
+- 单通道验证 Source 首次启动、停止、相同参数重复生效。
+- 分别改变协议、协议电压和协议电流，确认只执行一次重新 INIT。
+- 模拟协议板电压持续为零，确认进入 WAIT 且不会反复提交相同批次。
+- 验证 Source -> Sink、Sink -> Source，示波器确认切换期间无输出重叠。
+- 四通道同时运行并交叉切换，检查南向队列饥饿、响应错配、超时和缓存串通道。
+- 回归 Sink 正常负载、动态测试、无电流重启及低压处理。
+
+## 9. 接手注意事项
+
+开始修改前先执行 `git status --short` 和 `git diff`。当前 `chrg_north.c` 还包含此前 Sink 连续确认次数改为 3 的修改及注释清理，不能在 Source 重构时回退。不要提交 Keil `build/`、`Obj/`、AXF、BIN 或 MAP 等生成文件。