docs: 补充核心分层中文注释

2026-09-29 18:18:44 +08:00
parent a77471a7b1
commit 9fd01bb61b
81 changed files with 1189 additions and 112 deletions
@@ -10,6 +10,12 @@

 #include "driver/gpio.h"

+/*
+ * 控制面内部事件总线的数据契约：输入驱动只负责生成“发生了什么”，系统事件任务再决定
+ * “应该做什么”。这种拆分避免在 GPIO 中断或按键扫描任务里直接执行联网、播放、旋转等
+ * 可能阻塞的业务动作。这里的结构体会按值放入 FreeRTOS 队列，因此字段必须保持轻量，
+ * 不得加入需要跨任务管理生命周期的裸指针。
+ */
 typedef enum {
    CONTROL_PLANE_EVENT_FAMILY_KEY = 0,
    CONTROL_PLANE_EVENT_FAMILY_WIFI,
@@ -14,6 +14,11 @@
 #include "esp_err.h"
 #include "control_plane_events.h"

+/*
+ * control_plane 组件的私有协作接口，仅供本组件各编译单元使用。
+ * 公共入口放在 control_plane.h；这里暴露的是解析器、工作任务和多模态状态机之间的接缝，
+ * 不承诺跨组件 ABI 稳定性。函数若涉及阻塞等待，其超时和调用上下文由对应实现说明。
+ */
 control_plane_direction_command_t control_plane_direction_parse_command_internal(
        const char *input,
        size_t *out_direction_index);
@@ -14,6 +14,10 @@
 extern "C" {
 #endif

+/*
+ * 旧版多模态令牌服务的内部契约。长度宏同时约束 JSON 解析目标缓冲区和会话配置，
+ * 修改时必须与服务端字段上限一起核对，不能只为消除截断而盲目放大。
+ */
 #define CONTROL_PLANE_MULTIMODAL_AUTH_TOKEN_MAX_LEN 256
 #define CONTROL_PLANE_MULTIMODAL_AUTH_ID_MAX_LEN 64
 #define CONTROL_PLANE_MULTIMODAL_AUTH_VOICE_MAX_LEN 64
@@ -16,6 +16,10 @@
 extern "C" {
 #endif

+/*
+ * Device-JWT 认证引擎的组件内契约。调用方只消费按 scope 筛选后的 JWT；密钥生成、
+ * challenge/response、刷新退避和持久化均由实现封装，避免会话与 OTA 各自复制认证状态机。
+ */
 /*
 * Device-auth (device-JWT) engine, control-plane internal.
 *