终版

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;

User/stm32f10x_conf.h

@@ -67,6 +67,7 @@
   */
   #define assert_param(expr) ((expr) ? (void)0 : assert_failed((uint8_t *)__FILE__, __LINE__))
 /* Exported functions ------------------------------------------------------- */
+  /* 函数作用：在开启断言检查时报告参数断言失败所在的文件和行号。 */
   void assert_failed(uint8_t* file, uint32_t line);
 #else
   #define assert_param(expr) ((void)0)

User/stm32f10x_it.c

@@ -13,6 +13,7 @@ extern volatile uint32_t g_time_ms;
   * @brief  SysTick中断处理函数（1ms中断一次）
   * @note   用于维护系统时间戳和延时功能
   */
+/* 函数作用：每 1ms 递增系统毫秒计数，为延时和定时任务提供时间基准。 */
 void SysTick_Handler(void)
 {
     g_time_ms++;  // 每1ms递增一次
@@ -21,6 +22,7 @@ void SysTick_Handler(void)
 //... HardFault_Handler 等其他中断保持不变 ...
 
 // USART3中断（来自K210，根据连接图.md: K210使用USART3 PB10/PB11）
+/* 函数作用：接收 K210 串口发送的人脸识别结果，并按换行符组帧。 */
 void USART3_IRQHandler(void)
 {
     if (USART_GetITStatus(USART3, USART_IT_RXNE) == SET)

User/stm32f10x_it.h

@@ -21,18 +21,29 @@
 
 /* Exported functions ------------------------------------------------------- */
 
+/* 函数作用：处理不可屏蔽中断，当前项目中保留默认异常入口。 */
 void NMI_Handler(void);
+/* 函数作用：处理硬件错误异常，进入错误保护循环便于定位严重故障。 */
 void HardFault_Handler(void);
+/* 函数作用：处理内存管理异常，当前项目中保留默认异常入口。 */
 void MemManage_Handler(void);
+/* 函数作用：处理总线错误异常，当前项目中保留默认异常入口。 */
 void BusFault_Handler(void);
+/* 函数作用：处理未定义指令等用法错误异常，当前项目中保留默认异常入口。 */
 void UsageFault_Handler(void);
+/* 函数作用：处理系统服务调用异常，当前项目中保留默认异常入口。 */
 void SVC_Handler(void);
+/* 函数作用：处理调试监视异常，当前项目中保留默认异常入口。 */
 void DebugMon_Handler(void);
+/* 函数作用：处理可挂起系统服务异常，当前项目中保留默认异常入口。 */
 void PendSV_Handler(void);
+/* 函数作用：处理系统滴答定时器中断，用于毫秒计时和延时基准。 */
 void SysTick_Handler(void);
 
 // 外设中断
+/* 函数作用：处理 USART1 中断，用于 ESP8266 串口通信接收。 */
 void USART1_IRQHandler(void);
+/* 函数作用：处理 USART3 中断，用于 K210 人脸识别结果接收。 */
 void USART3_IRQHandler(void);
 
 #ifdef __cplusplus