feat(power): add controlled low-battery shutdown

components/domain/include/domain.h

@@ -67,9 +67,15 @@ esp_err_t domain_battery_sample(void);
 /** Copy the latest battery SSOT snapshot into `out_status`. */
 esp_err_t domain_battery_get_status(domain_battery_status_t *out_status);
 
-/** Reserved policy hook; this release intentionally performs no shutdown. */
+/** Enter the configured board deep-sleep state; a successful call does not return. */
 esp_err_t domain_battery_prepare_shutdown(void);
 
+/** Return true when the current boot resumed through a deep-sleep wake source. */
+bool domain_battery_woke_from_deep_sleep(void);
+
+/** Release low-power GPIO holds after accepting a deep-sleep wake. */
+void domain_battery_complete_wakeup(void);
+
 typedef enum {
     DOMAIN_WIFI_PROMPT_WIFI_SUCCESS = 0,
     DOMAIN_WIFI_PROMPT_AFTER_WIFI_SUCCESS,

components/domain/src/battery/domain_battery_service.c

@@ -40,6 +40,14 @@ typedef struct {
     uint8_t percentage;
 } battery_curve_point_t;
 
+typedef struct {
+    uint8_t version;
+    uint8_t reason;
+    uint8_t percentage;
+    uint8_t reserved;
+    int32_t voltage_mv;
+} battery_shutdown_record_t;
+
 static const battery_curve_point_t s_discharge_curve[] = {
     {3300, 0},
     {3400, 2},
@@ -329,8 +337,37 @@ esp_err_t domain_battery_get_status(domain_battery_status_t *out_status)
 
 esp_err_t domain_battery_prepare_shutdown(void)
 {
-    /* Reserved for a future board-specific sleep or power-cut sequence. */
+#if CONFIG_TQ_BATTERY_CONTROLLED_SHUTDOWN_ENABLE
+    battery_shutdown_record_t record = {
+        .version = 1U,
+        .reason = 1U,
+    };
+    if (lock_state()) {
+        record.percentage = s_status.percentage;
+        record.voltage_mv = s_status.voltage_mv;
+        unlock_state();
+    }
+    /* Best-effort bounded record; a storage failure must not block deep sleep. */
+    (void)platform_storage_set_blob("battery",
+                                    "last_shutdown",
+                                    &record,
+                                    sizeof(record));
+    return platform_power_enter_deep_sleep(
+            CONFIG_TQ_BATTERY_CHARGE_GPIO,
+            CONFIG_TQ_BATTERY_SHUTDOWN_WAKE_BUTTON_GPIO);
+#else
     return ESP_ERR_NOT_SUPPORTED;
+#endif
+}
+
+bool domain_battery_woke_from_deep_sleep(void)
+{
+    return platform_power_woke_from_deep_sleep();
+}
+
+void domain_battery_complete_wakeup(void)
+{
+    platform_power_release_deep_sleep_holds();
 }
 
 #else
@@ -358,4 +395,13 @@ esp_err_t domain_battery_prepare_shutdown(void)
     return ESP_ERR_NOT_SUPPORTED;
 }
 
+bool domain_battery_woke_from_deep_sleep(void)
+{
+    return false;
+}
+
+void domain_battery_complete_wakeup(void)
+{
+}
+
 #endif