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

components/app_composition/src/runtime/app_composition_default_runtime.c

@@ -14,6 +14,12 @@
 #include "freertos/task.h"
 #include "sdkconfig.h"
 
+/*
+ * 默认启动编排只负责“按什么顺序组装”，不实现 domain/control_plane 的业务逻辑。
+ * 顺序核心是：先建立存储和硬件基础，再恢复配置与网络，最后启动长期工作任务；这样后启动
+ * 的任务可以把前序服务视为稳定依赖。失败处理分为致命失败与可降级失败，见主序列各阶段说明。
+ */
+
 #ifndef CONFIG_TQ_BOOT_SEQUENCE_DRY_RUN
 #define CONFIG_TQ_BOOT_SEQUENCE_DRY_RUN 0
 #endif
@@ -26,6 +32,11 @@
 #define CONFIG_TQ_WIFI_CONNECT_CYCLE_TIMEOUT_MS 20000
 #endif
 
+/*
+ * 3 秒只约束开机提示，不应拖住完整启动；20 秒是一次 Wi-Fi 连接/配网周期的共享预算，
+ * 而不是每个内部重试都重新获得 20 秒。dry-run 用于验证阶段依赖和日志，不触碰真实外设。
+ */
+
 static const char *TAG = "app_comp_boot";
 
 typedef enum {
@@ -71,6 +82,7 @@ static void app_composition_log_stage_skipped(app_composition_boot_stage_t stage
 
 static esp_err_t app_composition_run_plan_a_boot_sequence(void)
 {
+    /* 每个阶段都在依赖满足后才进入；不要仅为缩短启动时间而随意交换这些调用。 */
     app_composition_log_stage(APP_COMPOSITION_BOOT_STAGE_POWER_HOLD,
                               "power_hold",
                               "configured_or_disabled_by_platform_core");
@@ -78,6 +90,7 @@ static esp_err_t app_composition_run_plan_a_boot_sequence(void)
     app_composition_log_stage(APP_COMPOSITION_BOOT_STAGE_STORAGE_PREPARE,
                               "storage_prepare",
                               "control_plane_prepare_runtime_storage");
+    /* 存储是身份、凭据和领域 SSOT 的前置依赖，失败后继续会制造“看似启动但状态无法保存”的假成功。 */
     esp_err_t err = control_plane_prepare_runtime_storage();
     if (err != ESP_OK) {
         ESP_LOGE(TAG, "Runtime storage prepare failed: %s", esp_err_to_name(err));
@@ -92,6 +105,7 @@ static esp_err_t app_composition_run_plan_a_boot_sequence(void)
                                      "wall_clock",
                                      wall_clock_err);
     if (wall_clock_err != ESP_OK) {
+        /* 时区失败只影响本地日期类功能，联网和设备控制仍可工作，因此按降级处理。 */
         ESP_LOGW(TAG,
                  "Local time zone setup failed, continue boot: %s",
                  esp_err_to_name(wall_clock_err));
@@ -109,6 +123,7 @@ static esp_err_t app_composition_run_plan_a_boot_sequence(void)
             control_plane_take_mini_program_recovery_boot_request();
 
     if (provisioning_recovery_boot) {
+        /* 恢复启动优先给 BLE 配网留出内部 RAM/DMA，暂不初始化音频和屏幕等大资源消费者。 */
         app_composition_log_stage_skipped(APP_COMPOSITION_BOOT_STAGE_AUDIO_INIT,
                                           "audio_init",
                                           "ble_recovery_boot");
@@ -138,6 +153,7 @@ static esp_err_t app_composition_run_plan_a_boot_sequence(void)
     }
 
 #if CONFIG_TQ_SCREEN_ENABLE
+    /* LCD 是可选呈现通道：设备或渲染任务失败不阻断无屏的核心控制/配网能力。 */
     app_composition_log_stage(APP_COMPOSITION_BOOT_STAGE_LCD_DEVICE,
                               "lcd_device",
                               "control_plane_init_lcd_device");
@@ -178,6 +194,7 @@ static esp_err_t app_composition_run_plan_a_boot_sequence(void)
     app_composition_log_stage(APP_COMPOSITION_BOOT_STAGE_PLATFORM_DOMAIN,
                               "platform_domain",
                               "control_plane_init");
+    /* control_plane/domain 初始化失败会使后续所有用例前提不成立，属于致命阶段。 */
     err = control_plane_init();
     if (err != ESP_OK) {
         ESP_LOGE(TAG, "control_plane_init failed: %s", esp_err_to_name(err));
@@ -192,6 +209,7 @@ static esp_err_t app_composition_run_plan_a_boot_sequence(void)
     }
 
 #if CONFIG_TQ_FACTORY_CLI_ENABLE
+    /* 工厂构建依赖 CLI 完成身份灌装；启用后无法启动应显式失败，避免产出未配置设备。 */
     if (!provisioning_recovery_boot) {
         err = control_plane_factory_cli_start();
         if (err != ESP_OK) {
@@ -223,6 +241,7 @@ static esp_err_t app_composition_run_plan_a_boot_sequence(void)
                                   "turntable_calibration",
                                   "control_plane_calibrate");
         esp_err_t calibration_err = control_plane_calibrate();
+        /* 校准失败仍允许联网和诊断启动，只把方向执行视为降级能力。 */
         if (calibration_err != ESP_OK) {
             ESP_LOGW(TAG,
                      "Boot turntable calibration failed, continue degraded: %s",
@@ -242,6 +261,7 @@ static esp_err_t app_composition_run_plan_a_boot_sequence(void)
                                                               CONFIG_MULTIMODAL_WIFI_PASSWORD,
                                                               CONFIG_TQ_WIFI_CONNECT_CYCLE_TIMEOUT_MS);
     if (wifi_err != ESP_OK) {
+        /* 联网失败可能由暂时离线造成；运行时重连策略仍需启动，因此这里只记录而不终止。 */
         ESP_LOGW(TAG, "Connectivity bootstrap failed: %s", esp_err_to_name(wifi_err));
     }
 
@@ -252,9 +272,11 @@ static esp_err_t app_composition_run_plan_a_boot_sequence(void)
                                       ? "deferred_until_ble_provisioning_completes"
                                       : "control_plane_start_runtime_workers");
     if (provisioning_active) {
+        /* BLE 配网 worker 完成后负责恢复完整运行时，当前启动线程不得重复创建同一批任务。 */
         ESP_LOGI(TAG,
                  "Full runtime workers deferred while BLE provisioning is active");
     } else {
+        /* 长期 worker 是在线恢复、事件分发等能力的宿主，非配网模式下启动失败不能伪装成功。 */
         err = control_plane_start_runtime_workers();
         if (err != ESP_OK) {
             ESP_LOGE(TAG, "Runtime worker start failed: %s", esp_err_to_name(err));