# 开机时钟小时偏差问题修复说明

## 1. 提交信息

- 提交：`f33ad70 fix(time): apply timezone before lcd startup`
- 现象：设备每次开机后，LCD 显示的分钟正确，但小时错误；网络连接并完成时间服务初始化后，小时恢复正确。
- 复现场景：普通重启、Deep Sleep 唤醒、开机后暂时没有网络。

## 2. 问题原因

ESP32 的系统时间和 RTC 时间使用 UTC 时间戳保存绝对时间。LCD 将时间戳转换成年、月、日、小时和分钟时，会通过 `localtime_r()` 使用当前进程的 `TZ` 环境变量进行本地时区换算。

旧实现只在 Wi-Fi 连接成功、准备启动 SNTP 时执行：

```c
setenv("TZ", posix_tz, 1);
tzset();
```

但 LCD 的初始化和渲染发生在 Wi-Fi 连接及 SNTP 启动之前。因此，设备刚启动时虽然 RTC 中保留的 UTC 时间戳仍然有效，但当前进程尚未设置中国标准时间时区，`localtime_r()` 会按 UTC 解释时间。这会产生以下特征：

- 分钟不受 UTC 与中国标准时间时差影响，所以分钟显示正确。
- 小时少 8 小时，因此小时显示错误。
- Wi-Fi 连接成功后，SNTP 启动流程设置 `TZ=CST-8`，小时随即恢复正确。

Deep Sleep 也会复现该问题，是因为 RTC 可以继续保留绝对时间，而应用进程重新启动后，进程级的 `TZ` 环境状态需要重新设置。也就是说，保留 RTC 时间并不等于保留本地时区配置。

修复前的启动顺序为：

```text
存储准备
-> 音频初始化
-> LCD 初始化及时间渲染
-> Wi-Fi 连接
-> 运行时任务启动
-> SNTP 启动并设置时区
```

问题本质不是 RTC 或 SNTP 保存了错误的小时，而是本地时区设置得太晚。

## 3. 解决方式

将“应用本地时区”和“通过网络同步绝对时间”拆分为两个可以独立执行的操作：

1. 新增不依赖网络的时区设置接口，只负责设置 `TZ` 并调用 `tzset()`。
2. 按照现有分层，通过 `platform -> domain -> control_plane -> app_composition` 逐层暴露该能力。
3. 在存储准备完成后、LCD 初始化之前增加 `wall_clock` 启动阶段，立即应用配置项 `CONFIG_TQ_TIME_POSIX_TZ`。
4. SNTP 仍在网络连接成功后启动，用于校准 UTC 绝对时间；启动 SNTP 时再次应用时区，作为后续保护。
5. 如果开机阶段设置时区失败，记录警告并继续启动，避免时区异常阻断整个设备启动流程。

修复后的启动顺序为：

```text
存储准备
-> 本地应用 CST-8 时区
-> 电池启动保护及音频初始化
-> LCD 初始化及时间渲染
-> Wi-Fi 连接
-> SNTP 校准绝对时间
```

其中，`CST-8` 是 POSIX 时区字符串。POSIX 的符号约定与通常书写习惯相反，`CST-8` 表示 UTC+8。

## 4. 具体代码

### 4.1 Platform 层：新增独立时区设置接口

公开接口声明：

```c
/**
 * @brief Wall-clock time synchronization (SNTP) primitives.
 *
 * - `platform_time_set_timezone()` applies the process-local POSIX time zone
 *   without starting SNTP. Call it during boot before local time is rendered.
 * - `platform_time_sync_start()` is idempotent: it sets the process time zone
 *   (`posix_tz`, e.g. "CST-8"; ignored when NULL/empty) on every call and
 *   starts the SNTP client once. Must be called after the network is up.
 * - `platform_time_is_synced()` reports whether the system clock has advanced
 *   past a sane epoch lower bound (i.e. SNTP has set the time at least once).
 */
esp_err_t platform_time_set_timezone(const char *posix_tz);
esp_err_t platform_time_sync_start(const char *sntp_server, const char *posix_tz);
bool platform_time_is_synced(void);
```

接口实现：

```c
esp_err_t platform_time_set_timezone(const char *posix_tz)
{
    if (posix_tz == NULL || posix_tz[0] == '\0') {
        return ESP_ERR_INVALID_ARG;
    }
    if (setenv("TZ", posix_tz, 1) != 0) {
        ESP_LOGE(TAG, "Set time zone failed (tz=%s)", posix_tz);
        return ESP_FAIL;
    }
    tzset();
    ESP_LOGI(TAG, "Local time zone applied (tz=%s)", posix_tz);
    return ESP_OK;
}
```

该实现先校验参数，再更新进程级 `TZ` 环境变量并刷新 C 运行库的时区换算规则。此过程不访问网络，也不修改 RTC 中的 UTC 时间戳。

### 4.2 Platform 层：SNTP 启动复用时区接口

```c
esp_err_t platform_time_sync_start(const char *sntp_server, const char *posix_tz)
{
    if (posix_tz != NULL && posix_tz[0] != '\0') {
        esp_err_t timezone_err = platform_time_set_timezone(posix_tz);
        if (timezone_err != ESP_OK) {
            return timezone_err;
        }
    }

    portENTER_CRITICAL(&s_time_lock);
    if (s_sntp_started) {
        portEXIT_CRITICAL(&s_time_lock);
        return ESP_OK;
    }
    s_sntp_started = true;
    portEXIT_CRITICAL(&s_time_lock);

    const char *server = (sntp_server != NULL && sntp_server[0] != '\0')
                             ? sntp_server
                             : "pool.ntp.org";

    esp_sntp_config_t config = ESP_NETIF_SNTP_DEFAULT_CONFIG(server);
    config.start = true;
    config.server_from_dhcp = false;

    esp_err_t err = esp_netif_sntp_init(&config);
    if (err != ESP_OK && err != ESP_ERR_INVALID_STATE) {
        portENTER_CRITICAL(&s_time_lock);
        s_sntp_started = false;
        portEXIT_CRITICAL(&s_time_lock);
        ESP_LOGE(TAG, "SNTP init failed: %s", esp_err_to_name(err));
        return err;
    }

    ESP_LOGI(TAG, "SNTP started (server=%s, tz=%s)",
             server, (posix_tz != NULL && posix_tz[0] != '\0') ? posix_tz : "<unset>");
    return ESP_OK;
}
```

SNTP 启动仍保持幂等。每次调用都会先应用有效的时区配置，但 SNTP 客户端只初始化一次。

### 4.3 Domain 层：桥接时区能力

公开接口声明：

```c
/**
 * @brief Wall-clock time synchronization, bridged to the platform SNTP
 *        primitive. `set_timezone` applies local-time conversion without
 *        network access. `start` is idempotent and also applies the process
 *        time zone (`posix_tz`, e.g. "CST-8"); `is_synced` reports whether the
 *        clock has been set. Call `start` after the network is up.
 */
esp_err_t domain_runtime_time_set_timezone(const char *posix_tz);
esp_err_t domain_runtime_time_sync_start(const char *sntp_server, const char *posix_tz);
bool domain_runtime_time_is_synced(void);
```

桥接实现：

```c
esp_err_t domain_runtime_time_set_timezone(const char *posix_tz)
{
    return platform_time_set_timezone(posix_tz);
}
```

### 4.4 Control Plane 层：使用项目配置准备本地时钟

时区配置缺省值：

```c
#ifndef CONFIG_TQ_TIME_POSIX_TZ
#define CONFIG_TQ_TIME_POSIX_TZ "CST-8"
#endif
```

公开接口声明：

```c
/** Apply the configured local time zone before any local time is rendered. */
esp_err_t control_plane_prepare_wall_clock(void);
```

接口实现：

```c
esp_err_t control_plane_prepare_wall_clock(void)
{
    return domain_runtime_time_set_timezone(CONFIG_TQ_TIME_POSIX_TZ);
}
```

### 4.5 App Composition 层：增加开机阶段

启动阶段枚举中增加 `APP_COMPOSITION_BOOT_STAGE_WALL_CLOCK`：

```c
typedef enum {
    APP_COMPOSITION_BOOT_STAGE_POWER_HOLD = 1,
    APP_COMPOSITION_BOOT_STAGE_STORAGE_PREPARE,
    APP_COMPOSITION_BOOT_STAGE_WALL_CLOCK,
    APP_COMPOSITION_BOOT_STAGE_AUDIO_INIT,
    APP_COMPOSITION_BOOT_STAGE_BOOT_SOUND,
    APP_COMPOSITION_BOOT_STAGE_AUDIO_READY,
    APP_COMPOSITION_BOOT_STAGE_LCD_DEVICE,
    APP_COMPOSITION_BOOT_STAGE_LCD_RENDER_LOOP,
    APP_COMPOSITION_BOOT_STAGE_PLATFORM_DOMAIN,
    APP_COMPOSITION_BOOT_STAGE_TURNTABLE_CALIBRATION,
    APP_COMPOSITION_BOOT_STAGE_WIFI_BOOTSTRAP,
    APP_COMPOSITION_BOOT_STAGE_RUNTIME_WORKERS,
    APP_COMPOSITION_BOOT_STAGE_NETWORK_SERVICES,
} app_composition_boot_stage_t;
```

在存储准备完成之后、LCD 和网络初始化之前调用：

```c
app_composition_log_stage(APP_COMPOSITION_BOOT_STAGE_WALL_CLOCK,
                          "wall_clock",
                          "control_plane_prepare_wall_clock");
esp_err_t wall_clock_err = control_plane_prepare_wall_clock();
app_composition_log_stage_result(APP_COMPOSITION_BOOT_STAGE_WALL_CLOCK,
                                 "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));
}
```

## 5. 解决成果

- 代码路径已确保在 LCD 首次渲染时间前应用 `CST-8`；RTC 时间有效时，开机阶段即可显示正确的中国标准时间。
- 从启动顺序上消除了普通重启和 Deep Sleep 唤醒后等待 Wi-Fi 才能修正小时的问题。
- 从实现上支持离线启动时根据 RTC 中保留的 UTC 时间换算本地小时。
- 分钟显示逻辑和原有 LCD 更新时间隔保持不变。
- SNTP 职责保持不变，网络连接后仍负责校准绝对时间。
- 已使用 ESP-IDF v5.5.4 完成编译验证，构建成功；普通重启、Deep Sleep 和断网启动仍建议按第 6.6 节进行实机回归。
- 固件大小为 `0x217f20`，应用分区剩余 `0x1680e0`，约 40%。

## 6. 后续是否有其他影响

### 6.1 内存和性能影响

本次修改没有新增任务、定时器、帧缓冲、动态内存分配或 PSRAM 分配。新增内容主要是函数调用、少量代码和日志字符串，对内部 RAM 的持续占用基本无可感知变化，也不需要为了该修复将内部 RAM 改为 PSRAM。

开机时只增加一次 `setenv()`、`tzset()` 和日志输出，执行耗时相对于完整启动流程可以忽略。SNTP 启动时会再次调用时区设置接口，但不会重复启动 SNTP 客户端。

### 6.2 全局时区影响

`TZ` 是进程级全局配置。设置为 `CST-8` 后，项目内所有使用 `localtime()` 或 `localtime_r()` 的模块都会采用同一时区。这符合设备当前统一使用中国标准时间的预期；如果未来需要同时显示多个地区的时间，不能依赖反复修改全局 `TZ`，需要增加独立的时区换算方案。

### 6.3 启动日志和阶段编号

启动日志会新增一个 `wall_clock` 阶段以及一条时区应用成功日志。由于枚举中插入了新的阶段，后续启动阶段的数字编号会顺延一位；阶段名称和启动行为不受影响。如果外部日志分析程序依赖数字编号，需要同步调整。

### 6.4 异常降级行为

若时区字符串为空或设置失败，启动流程不会被中断，而是输出警告后继续。此时 LCD 可能暂时按 UTC 显示；网络连接后 SNTP 启动流程会再次尝试应用时区。

### 6.5 RTC 无有效时间的情况

本次修复只解决“UTC 时间有效，但本地时区尚未应用”的问题，不负责在完全断电且没有可靠 RTC 时间来源时生成正确绝对时间。如果冷启动时系统时间无效，LCD 应继续显示 `--:--`，直到网络连接并由 SNTP 完成校时。时区设置不能替代 SNTP 校时。

### 6.6 建议的硬件回归验证

建议在实机上继续覆盖以下场景：

- RTC 时间有效时进行普通软件重启，确认首屏小时和分钟均正确。
- 进入 Deep Sleep 后唤醒，确认联网前的小时正确。
- 断开网络启动，确认 RTC 有效时仍能按 UTC+8 显示。
- 网络恢复并完成 SNTP 同步，确认时间连续且没有异常跳变。
- 完全断电导致 RTC 时间无效时，确认同步前显示 `--:--`，同步后恢复正确时间。

## 7. 结论

该问题由启动阶段未及时恢复进程级时区引起，与分钟计算、LCD 渲染或 RTC 走时精度无关。修复通过在 LCD 启动前独立应用 `CST-8`，使设备不依赖网络也能将有效的 UTC 时间换算为正确本地时间；网络连接后的 SNTP 继续负责绝对时间校准。改动不新增常驻内存资源，主要影响仅为新增启动日志、启动阶段编号顺延和全局本地时区提前生效。