# 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 等生成文件。