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

components/domain/src/runtime/domain_runtime_adapters.c

@@ -16,6 +16,12 @@
 #include "esp_log.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/portmacro.h"
+
+/*
+ * Domain 运行时适配器：把领域层端口翻译成 platform 调用，并把平台事件映射回领域语义。
+ * 本文件不应引入重试、状态机或产品策略；这些属于 control_plane。静态回调及 hook 是注册
+ * 信息的唯一副本，分发时先在临界区内取得快照，再在锁外调用，防止回调重入造成死锁。
+ */
 #include "sdkconfig.h"
 
 #ifndef CONFIG_MULTIMODAL_PTT_BUTTON_GPIO
@@ -138,8 +144,12 @@ static const char *const s_wealth_direction_asset_dirs[] = {
 #define DOMAIN_WUXING_REVEAL_FRAME_MS 100U
 #define DOMAIN_WUXING_HOLD_FRAME_MS 500U
 
+/* 动画节奏属于领域呈现契约：短帧展示运动过程，较长末帧让用户有时间辨认最终结果。 */
+
 #define DOMAIN_AUTH_KEY_STORE_NAMESPACE "auth_key"
 #define DOMAIN_AUTH_STATE_STORE_NAMESPACE "auth"
+
+/* 认证密钥与认证状态分命名空间保存，便于独立轮换密钥而不破坏注册进度。 */
 #define DOMAIN_AUTH_KEY_STORE_BLOB_KEY "keymat"
 #define DOMAIN_AUTH_STATE_STORE_BLOB_KEY "state"
 #define DOMAIN_AUTH_LEGACY_KEY_PRIV_KEY "sk"
@@ -304,6 +314,7 @@ static const domain_expression_catalog_entry_t s_expression_catalog[] = {
 
 static void snapshot_domain_wifi_behavior_hooks(domain_wifi_behavior_hooks_t *out_hooks)
 {
+    /* 只在临界区复制函数指针和上下文；实际 hook 在锁外调用，允许 hook 反向更新注册。 */
     if (out_hooks == NULL) {
         return;
     }
@@ -392,6 +403,7 @@ static void dispatch_domain_transport_event(domain_multimodal_transport_event_ty
                                             const uint8_t *data,
                                             size_t data_len)
 {
+    /* data 只在本次 platform 回调期间有效；domain 不缓存，跨任务保留由上层自行复制。 */
     domain_multimodal_transport_event_callback_t cb = NULL;
     void *cb_user_data = NULL;
     snapshot_domain_transport_callback(&cb, &cb_user_data);
@@ -576,6 +588,7 @@ esp_err_t domain_runtime_post_json(const char *url,
                                    size_t *out_response_body_len,
                                    int *out_status)
 {
+    /* 本适配只映射 header/缓冲区所有权，不解释业务 HTTP 状态，也不在 domain 内隐式重试。 */
     if (out_response_body_len != NULL) {
         *out_response_body_len = 0U;
     }
@@ -1116,6 +1129,7 @@ static esp_err_t load_legacy_auth_record(domain_runtime_auth_record_t record,
                                          size_t out_len,
                                          size_t *out_len_actual)
 {
+    /* 旧键只用于一次兼容读取；成功后由新格式保存路径接管，迁移不会改变调用方序列化 schema。 */
     switch (record) {
         case DOMAIN_RUNTIME_AUTH_RECORD_KEY_MATERIAL:
             return load_legacy_auth_key_material(out, out_len, out_len_actual);
@@ -1180,6 +1194,7 @@ esp_err_t domain_runtime_auth_store_save_record(domain_runtime_auth_record_t rec
                                                 const void *data,
                                                 size_t len)
 {
+    /* platform blob 写入成功才更新持久状态；输入缓冲区始终由调用方拥有。 */
     if (data == NULL || len == 0U) {
         return ESP_ERR_INVALID_ARG;
     }
@@ -1430,6 +1445,7 @@ static esp_err_t domain_resolve_expression_platform_request(
         const domain_expression_request_t *request,
         platform_lcd_presentation_request_t *out_platform_request)
 {
+    /* 这是领域表情 ID 到平台资源序列的唯一映射，避免 control_plane 拼接资源目录和帧参数。 */
     if (request == NULL || out_platform_request == NULL) {
         return ESP_ERR_INVALID_ARG;
     }
@@ -1621,6 +1637,7 @@ esp_err_t domain_runtime_preheat_expression(const domain_expression_request_t *r
 esp_err_t domain_runtime_request_expression_blocking(const domain_expression_request_t *request,
                                                      uint32_t timeout_ms)
 {
+    /* 仅有限序列适合等待完成；底层仍拥有渲染任务，调用方只是等待该请求的完成通知。 */
     /* Snapshot the playback completion counter before queuing so the wait stays
      * robust to the asynchronous request not having started yet. */
     uint32_t since_count = platform_lcd_presentation_completion_count();