终版

Hardware/Attendance.h

@@ -51,29 +51,51 @@ typedef struct {
 } TimeSlot;
 
 // 函数声明
+// 函数作用：初始化考勤模块的记录缓存、时间段配置和运行状态。
 void Attendance_Init(void);
-void Attendance_SetCurrentTime(uint8_t hour, uint8_t minute);  // 设置当前时间
-void Attendance_UpdateTimeSlots(TimeSlot* slots, uint8_t count); // 更新时间段配置（从服务器下载后调用）
-uint8_t Attendance_ParseTimeSlotsJSON(const char* json_str);    // 从JSON字符串解析时间段配置
+// 函数作用：设置考勤模块当前使用的小时和分钟，用于判断当前是否处于考勤时段。
+void Attendance_SetCurrentTime(uint8_t hour, uint8_t minute);
+// 函数作用：使用服务器下发的时间段数组更新本地考勤时间段配置。
+void Attendance_UpdateTimeSlots(TimeSlot* slots, uint8_t count);
+// 函数作用：从服务器返回的 JSON 字符串中解析时间段配置并更新本地列表。
+uint8_t Attendance_ParseTimeSlotsJSON(const char* json_str);
+// 函数作用：处理 K210 人脸识别结果，判断是否可打卡并生成考勤记录。
 AttendanceStatus Attendance_ProcessFaceResult(FaceRecognitionResult* result);
+// 函数作用：检查指定学号在当前考勤时段内是否已经打卡。
 uint8_t Attendance_IsDuplicate(const char* student_id);
-uint8_t Attendance_IsDuplicateOnServer(const char* student_id);  // 服务器端查重
-void Attendance_GetCurrentSlotTime(char* start_time, char* end_time);  // 获取当前时段时间
-uint8_t Attendance_LoadTodayRecordsFromServer(void);  // 新增：从服务器加载今日签到记录
-uint8_t Attendance_IsDuplicateInCache(const char* student_id);  // 新增：在本地缓存中查重
-void Attendance_AddToCache(const char* student_id);  // 新增：添加学号到缓存
-void Attendance_ClearCache(void);  // 新增：清空缓存
+// 函数作用：通过服务器接口检查指定学号在当前时段是否已经打卡。
+uint8_t Attendance_IsDuplicateOnServer(const char* student_id);
+// 函数作用：获取当前考勤时段的开始和结束时间字符串。
+void Attendance_GetCurrentSlotTime(char* start_time, char* end_time);
+// 函数作用：从服务器加载今日已签到记录，用于设备重启后恢复去重缓存。
+uint8_t Attendance_LoadTodayRecordsFromServer(void);
+// 函数作用：在本地今日签到缓存中检查指定学号是否已存在。
+uint8_t Attendance_IsDuplicateInCache(const char* student_id);
+// 函数作用：把指定学号加入本地今日签到缓存。
+void Attendance_AddToCache(const char* student_id);
+// 函数作用：清空本地今日签到缓存。
+void Attendance_ClearCache(void);
+// 函数作用：清空本地保存的考勤记录和同步状态。
 void Attendance_ClearRecords(void);
-uint16_t Attendance_GetTotalCount(void);      // 获取累计考勤总数
-uint16_t Attendance_GetActiveCount(void);     // 获取当前缓存记录数
-int8_t Attendance_GetCurrentTimeSlot(void);   // 获取当前时段编号（-1表示不在考勤时段）
+// 函数作用：返回累计考勤记录总数。
+uint16_t Attendance_GetTotalCount(void);
+// 函数作用：返回当前本地缓存中的有效记录数量。
+uint16_t Attendance_GetActiveCount(void);
+// 函数作用：返回当前所在考勤时段编号，-1 表示不在任意考勤时段。
+int8_t Attendance_GetCurrentTimeSlot(void);
 
 // 数据同步相关函数
-uint16_t Attendance_GetPendingCount(void);                        // 获取待同步记录数量（PENDING状态）
-AttendanceRecord* Attendance_GetNextPendingRecord(uint16_t* index); // 获取下一个待同步记录
-void Attendance_MarkSyncStatus(uint16_t index, SyncStatus status); // 更新记录的同步状态
-void Attendance_IncrementRetry(uint16_t index);                   // 增加重试计数
-AttendanceRecord* Attendance_GetRecordByIndex(uint16_t index);    // 按索引获取记录
-void Attendance_ResetFailedRecords(void);                         // 将所有FAILED记录重置为PENDING
+// 函数作用：统计当前处于待同步状态的考勤记录数量。
+uint16_t Attendance_GetPendingCount(void);
+// 函数作用：查找下一条待同步记录，并通过 index 返回其在缓存中的位置。
+AttendanceRecord* Attendance_GetNextPendingRecord(uint16_t* index);
+// 函数作用：按缓存索引更新指定考勤记录的同步状态。
+void Attendance_MarkSyncStatus(uint16_t index, SyncStatus status);
+// 函数作用：按缓存索引增加指定考勤记录的同步重试次数。
+void Attendance_IncrementRetry(uint16_t index);
+// 函数作用：按缓存索引返回指定考勤记录指针。
+AttendanceRecord* Attendance_GetRecordByIndex(uint16_t index);
+// 函数作用：将所有同步失败记录重置为待同步，便于后续重新上传。
+void Attendance_ResetFailedRecords(void);
 
 #endif