终版

User/main.c

@@ -84,11 +84,13 @@ uint32_t last_process_time = 0;
 #define PROCESS_INTERVAL_MS  2000
 
 /* --- 辅助函数 --- */
+/* 函数作用：判断指定年份是否为闰年。 */
 static uint8_t IsLeapYear(uint16_t year)
 {
     return ((year % 4 == 0 && year % 100 != 0) || (year % 400 == 0)) ? 1 : 0;
 }
 
+/* 函数作用：返回指定年份和月份对应的天数。 */
 static uint8_t DaysInMonth(uint16_t year, uint8_t month)
 {
     static const uint8_t days_table[12] = {31,28,31,30,31,30,31,31,30,31,30,31};
@@ -97,6 +99,7 @@ static uint8_t DaysInMonth(uint16_t year, uint8_t month)
     return days_table[month - 1];
 }
 
+/* 函数作用：在没有 DS1302 可用时，用系统 tick 推进软件时钟一秒。 */
 static void AdvanceSoftwareClockOneSecond(void)
 {
     g_current_time.second++;
@@ -122,6 +125,7 @@ static void AdvanceSoftwareClockOneSecond(void)
     g_current_time.year++;
 }
 
+/* 函数作用：启动签到成功提示音和成功指示灯。 */
 void StartBeepSuccess(void)
 {
     BUZZER_OFF();
@@ -133,6 +137,7 @@ void StartBeepSuccess(void)
     LED_SUCCESS_ON();
 }
 
+/* 函数作用：启动重复签到提示音和指示灯闪烁序列。 */
 void StartBeepDuplicate(void)
 {
     BUZZER_OFF();
@@ -144,6 +149,7 @@ void StartBeepDuplicate(void)
     LED_SUCCESS_ON();
 }
 
+/* 函数作用：在主循环中推进蜂鸣器和指示灯的非阻塞提示状态。 */
 void ProcessBeep(void)
 {
     if (beep_state == BEEP_IDLE) {
@@ -185,6 +191,7 @@ void ProcessBeep(void)
     }
 }
 
+/* 函数作用：刷新空闲状态下 OLED 显示的系统状态和待同步数量。 */
 void UpdateIdleScreen(void)
 {
     OLED_Clear();
@@ -203,6 +210,7 @@ void UpdateIdleScreen(void)
 /**
  * @brief 发送加密的考勤记录到服务器（新版本）
  */
+/* 函数作用：将一条考勤记录组装为 JSON，加密后通过 ESP8266 上传服务器。 */
 uint8_t SendEncryptedAttendance(AttendanceRecord* record)
 {
     char json_data[256];
@@ -244,6 +252,7 @@ uint8_t SendEncryptedAttendance(AttendanceRecord* record)
     }
 }
 
+/* 函数作用：批量同步本地待上传考勤记录，并根据结果更新同步状态。 */
 void SyncPendingRecords(void)
 {
     uint32_t current_time = Get_Time_ms();
@@ -312,6 +321,7 @@ void SyncPendingRecords(void)
                synced_count, failed_count);
 }
 
+/* 函数作用：从服务器同步网络时间，并在 DS1302 可用时写入 RTC。 */
 uint8_t SyncNetworkTime(void)
 {
     DEBUG_INFO("Syncing time from network...");
@@ -376,6 +386,7 @@ uint8_t SyncNetworkTime(void)
     return 0;
 }
 
+/* 函数作用：从同步状态 JSON 中提取服务端版本号。 */
 static uint32_t ParseSyncVersion(const char* json)
 {
     const char* p;
@@ -395,6 +406,7 @@ static uint32_t ParseSyncVersion(const char* json)
     return version;
 }
 
+/* 函数作用：从服务端下载 STM32 需要的同步状态并更新时间段配置。 */
 uint8_t DownloadTimeSlots(void)
 {
     char response_buffer[768];
@@ -444,6 +456,7 @@ uint8_t DownloadTimeSlots(void)
     return 0;
 }
 
+/* 函数作用：按固定间隔自动从服务端刷新时间段配置。 */
 void UpdateTimeSlotConfig(void)
 {
     uint32_t current_time = Get_Time_ms();
@@ -471,6 +484,7 @@ void UpdateTimeSlotConfig(void)
     }
 }
 
+/* 函数作用：更新当前时间来源，优先读取 DS1302，失败时使用软件时钟并定期 NTP 校时。 */
 void UpdateCurrentTime(void)
 {
     uint32_t current_ms = Get_Time_ms();
@@ -530,6 +544,7 @@ void UpdateCurrentTime(void)
     }
 }
 
+/* 函数作用：按重连间隔尝试恢复 WiFi，并在成功后连接 HTTP 服务器和同步配置。 */
 uint8_t TryReconnectWiFi(void)
 {
     uint32_t current_time = Get_Time_ms();
@@ -585,6 +600,7 @@ uint8_t TryReconnectWiFi(void)
     return 0;
 }
 
+/* 函数作用：按重连间隔尝试恢复 HTTP 服务器连接。 */
 uint8_t TryReconnectServer(void)
 {
     uint32_t current_time = Get_Time_ms();
@@ -616,6 +632,7 @@ uint8_t TryReconnectServer(void)
     return 0;
 }
 
+/* 函数作用：周期性检查服务器连接状态，断线时触发自动重连。 */
 void CheckServerConnection(void)
 {
     uint32_t current_time = Get_Time_ms();
@@ -653,6 +670,7 @@ void CheckServerConnection(void)
 // ======================================================================
 //                             主函数
 // ======================================================================
+/* 函数作用：STM32 固件入口，完成硬件初始化并循环处理识别、考勤、联网和显示任务。 */
 int main(void)
 {
     AttendanceStatus att_status;