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

components/platform/src/platform_battery_driver.c

@@ -25,6 +25,11 @@
 
 #if CONFIG_TQ_BATTERY_ENABLE
 
+/*
+ * 每次采16个样本并裁掉最低/最高各4个，剩余8个取均值；200us 间隔用于跨越短促
+ * 开关噪声。2500-4500mV 只是硬件合理性范围，不是 SOC 阈值；越界样本标记无效，
+ * domain 层不得把它直接解释为没电。
+ */
 #define BATTERY_ADC_SAMPLE_COUNT       16
 #define BATTERY_ADC_TRIM_COUNT         4
 #define BATTERY_VALID_MIN_MV           2500
@@ -43,6 +48,7 @@ static portMUX_TYPE s_state_lock = portMUX_INITIALIZER_UNLOCKED;
 static uint16_t s_load_ref_count[PLATFORM_BATTERY_LOAD_COUNT];
 static int64_t s_cooldown_until_us;
 
+/* ADC 读取可能跨任务发生，使用有界互斥等待防止采样路径无限阻塞。 */
 static bool lock_adc(void)
 {
     if (s_adc_lock == NULL) {
@@ -81,6 +87,7 @@ static void sort_ints(int *values, size_t count)
 
 static esp_err_t create_calibration(adc_unit_t unit, adc_channel_t channel)
 {
+    /* 优先曲线拟合，芯片不支持时回退到线性拟合校准方案。 */
 #if ADC_CALI_SCHEME_CURVE_FITTING_SUPPORTED
     {
         adc_cali_curve_fitting_config_t config = {
@@ -204,6 +211,7 @@ esp_err_t platform_battery_init(void)
 
 static void snapshot_load_state(bool *out_active, bool *out_cooldown)
 {
+    /* active 表示当前高负载，cooldown 表示负载刚结束且电压尚未完全恢复。 */
     bool active = false;
     int64_t cooldown_until_us = 0;
 
@@ -223,6 +231,7 @@ static void snapshot_load_state(bool *out_active, bool *out_cooldown)
 
 esp_err_t platform_battery_read_sample(platform_battery_sample_t *out_sample)
 {
+    /* 多次采样排序后去除两端异常值，以降低电机和音频负载造成的瞬态噪声。 */
     if (out_sample == NULL) {
         return ESP_ERR_INVALID_ARG;
     }
@@ -262,6 +271,7 @@ esp_err_t platform_battery_read_sample(platform_battery_sample_t *out_sample)
     }
 
     sort_ints(samples_mv, BATTERY_ADC_SAMPLE_COUNT);
+    /* 对称裁剪最高/最低样本后取均值，抑制开关噪声但保留缓慢电压变化。 */
     int64_t sum_mv = 0;
     for (size_t i = BATTERY_ADC_TRIM_COUNT;
          i < BATTERY_ADC_SAMPLE_COUNT - BATTERY_ADC_TRIM_COUNT;
@@ -297,6 +307,7 @@ esp_err_t platform_battery_read_sample(platform_battery_sample_t *out_sample)
 
 void platform_battery_load_begin(platform_battery_load_source_t source)
 {
+    /* 饱和递增防止异常嵌套调用造成引用计数回绕。 */
     if (source < 0 || source >= PLATFORM_BATTERY_LOAD_COUNT) {
         return;
     }
@@ -309,6 +320,7 @@ void platform_battery_load_begin(platform_battery_load_source_t source)
 
 void platform_battery_load_end(platform_battery_load_source_t source)
 {
+    /* 最后一个负载结束时启动冷却窗口，给电池端电压留出恢复时间。 */
     if (source < 0 || source >= PLATFORM_BATTERY_LOAD_COUNT) {
         return;
     }