终版

Hardware/Attendance.c

@@ -32,6 +32,7 @@ static AttendanceRecord attendance_records[MAX_ATTENDANCE_RECORDS];
 static uint16_t record_count = 0;
 static uint32_t total_attendance_count = 0;  // 总考勤人次
 
+/* 函数作用：根据当前小时和分钟查找所处的考勤时间段。 */
 static int8_t Attendance_FindTimeSlot(uint8_t hour, uint8_t minute)
 {
     uint16_t current_minutes = hour * 60 + minute;
@@ -57,6 +58,7 @@ static int8_t Attendance_FindTimeSlot(uint8_t hour, uint8_t minute)
 /**
   * @brief  初始化考勤模块
   */
+/* 函数作用：初始化考勤记录、时间段配置和今日已签到缓存。 */
 void Attendance_Init(void)
 {
     record_count = 0;
@@ -81,6 +83,7 @@ void Attendance_Init(void)
 /**
   * @brief  清空今日签到缓存
   */
+/* 函数作用：清空当前时段的服务器已签到学号缓存。 */
 void Attendance_ClearCache(void)
 {
     cached_id_count = 0;
@@ -93,6 +96,7 @@ void Attendance_ClearCache(void)
 /**
   * @brief  添加学号到缓存
   */
+/* 函数作用：把指定学号加入当前考勤时段的本地查重缓存。 */
 void Attendance_AddToCache(const char* student_id)
 {
     int8_t current_slot = Attendance_GetCurrentTimeSlot();
@@ -132,6 +136,7 @@ void Attendance_AddToCache(const char* student_id)
   * @brief  在本地缓存中查重
   * @retval 1=在缓存中找到（重复）, 0=未找到
   */
+/* 函数作用：检查指定学号是否已存在于当前时段缓存中。 */
 uint8_t Attendance_IsDuplicateInCache(const char* student_id)
 {
     int8_t current_slot = Attendance_GetCurrentTimeSlot();
@@ -158,6 +163,7 @@ uint8_t Attendance_IsDuplicateInCache(const char* student_id)
   * @brief  从服务器加载今日已签到记录到缓存
   * @retval 加载的记录数量
   */
+/* 函数作用：下载当前时段已签到学号列表并写入本地查重缓存。 */
 uint8_t Attendance_LoadTodayRecordsFromServer(void)
 {
     char slot_start[8];
@@ -221,6 +227,7 @@ uint8_t Attendance_LoadTodayRecordsFromServer(void)
   * @param  slots 新的时间段配置数组
   * @param  count 时间段数量
   */
+/* 函数作用：用服务端下发的新时间段数组替换本地时间段配置。 */
 void Attendance_UpdateTimeSlots(TimeSlot* slots, uint8_t count)
 {
     if (count > MAX_TIME_SLOT_COUNT) {
@@ -249,6 +256,7 @@ void Attendance_UpdateTimeSlots(TimeSlot* slots, uint8_t count)
   * @param  json_str JSON字符串（格式：{"time_slots":[{"enabled":true,"start_time":"08:00",...}]}）
   * @retval 成功解析的时间段数量
   */
+/* 函数作用：从服务端同步 JSON 中解析时间段配置并应用到本地。 */
 uint8_t Attendance_ParseTimeSlotsJSON(const char* json_str)
 {
     TimeSlot temp_slots[MAX_TIME_SLOT_COUNT];
@@ -386,6 +394,7 @@ uint8_t Attendance_ParseTimeSlotsJSON(const char* json_str)
   * @param  hour 小时 (0-23)
   * @param  minute 分钟 (0-59)
   */
+/* 函数作用：更新考勤模块当前时间，并在跨时段时清空查重缓存。 */
 void Attendance_SetCurrentTime(uint8_t hour, uint8_t minute)
 {
     int8_t old_slot = Attendance_FindTimeSlot(current_hour, current_minute);
@@ -405,6 +414,7 @@ void Attendance_SetCurrentTime(uint8_t hour, uint8_t minute)
   * @brief  获取当前所处的考勤时段
   * @retval 时段编号 (0-N)，如果不在任何时段内则返回 -1
   */
+/* 函数作用：返回当前时间对应的考勤时段索引。 */
 int8_t Attendance_GetCurrentTimeSlot(void)
 {
     return Attendance_FindTimeSlot(current_hour, current_minute);
@@ -415,6 +425,7 @@ int8_t Attendance_GetCurrentTimeSlot(void)
   * @param  start_time 输出：开始时间（格式"HH:MM"）
   * @param  end_time 输出：结束时间（格式"HH:MM"）
   */
+/* 函数作用：输出当前考勤时段的开始和结束时间字符串。 */
 void Attendance_GetCurrentSlotTime(char* start_time, char* end_time)
 {
     int8_t current_slot = Attendance_GetCurrentTimeSlot();
@@ -438,6 +449,7 @@ void Attendance_GetCurrentSlotTime(char* start_time, char* end_time)
   * @param  student_id 学生学号
   * @retval 1=服务器显示已签到（重复）, 0=未签到或查询失败
   */
+/* 函数作用：向服务器查询指定学生在当前时段是否已经签到。 */
 uint8_t Attendance_IsDuplicateOnServer(const char* student_id)
 {
     char slot_start[8];
@@ -458,6 +470,7 @@ uint8_t Attendance_IsDuplicateOnServer(const char* student_id)
   * @param  student_id 学生学号
   * @retval 1=重复, 0=不重复
   */
+/* 函数作用：检查指定学生是否已在当前时段产生本地重复签到。 */
 uint8_t Attendance_IsDuplicate(const char* student_id)
 {
     int8_t current_slot = Attendance_GetCurrentTimeSlot();
@@ -485,6 +498,7 @@ uint8_t Attendance_IsDuplicate(const char* student_id)
   * @param  result 人脸识别结果
   * @retval 考勤状态
   */
+/* 函数作用：校验识别结果、查重并生成一条待同步考勤记录。 */
 AttendanceStatus Attendance_ProcessFaceResult(FaceRecognitionResult* result)
 {
     // 1. 检查识别是否成功
@@ -598,6 +612,7 @@ AttendanceStatus Attendance_ProcessFaceResult(FaceRecognitionResult* result)
 /**
   * @brief  清空所有考勤记录
   */
+/* 函数作用：清空当前缓存的考勤记录，但保留累计统计值。 */
 void Attendance_ClearRecords(void)
 {
     record_count = 0;
@@ -608,6 +623,7 @@ void Attendance_ClearRecords(void)
 /**
   * @brief  获取累计考勤总数
   */
+/* 函数作用：返回系统启动以来累计处理的成功考勤次数。 */
 uint16_t Attendance_GetTotalCount(void)
 {
     return total_attendance_count;
@@ -616,6 +632,7 @@ uint16_t Attendance_GetTotalCount(void)
 /**
   * @brief  获取当前缓存中的记录数
   */
+/* 函数作用：返回当前本地缓存中的考勤记录数量。 */
 uint16_t Attendance_GetActiveCount(void)
 {
     return record_count;
@@ -625,6 +642,7 @@ uint16_t Attendance_GetActiveCount(void)
   * @brief  获取待同步记录的数量（PENDING或FAILED状态）
   * @retval 待同步记录数
   */
+/* 函数作用：统计当前等待上传或需要重试上传的记录数量。 */
 uint16_t Attendance_GetPendingCount(void)
 {
     uint16_t count = 0;
@@ -644,6 +662,7 @@ uint16_t Attendance_GetPendingCount(void)
   * @param  index 输出参数，返回记录的索引
   * @retval 记录指针，如果没有待同步记录则返回NULL
   */
+/* 函数作用：按优先级取出下一条可上传或可重试的考勤记录。 */
 AttendanceRecord* Attendance_GetNextPendingRecord(uint16_t* index)
 {
     uint32_t current_time = Get_Time_ms();
@@ -690,6 +709,7 @@ AttendanceRecord* Attendance_GetNextPendingRecord(uint16_t* index)
   * @param  index 记录索引
   * @param  status 新的同步状态
   */
+/* 函数作用：更新指定考勤记录的服务器同步状态。 */
 void Attendance_MarkSyncStatus(uint16_t index, SyncStatus status)
 {
     if (index < record_count)
@@ -711,6 +731,7 @@ void Attendance_MarkSyncStatus(uint16_t index, SyncStatus status)
   * @brief  增加记录的重试计数
   * @param  index 记录索引
   */
+/* 函数作用：增加指定记录的上传重试次数。 */
 void Attendance_IncrementRetry(uint16_t index)
 {
     if (index < record_count)
@@ -724,6 +745,7 @@ void Attendance_IncrementRetry(uint16_t index)
 /**
   * @brief  将所有FAILED记录重置为PENDING（用于网络恢复后）
   */
+/* 函数作用：网络恢复后把失败记录重新置为待同步状态。 */
 void Attendance_ResetFailedRecords(void)
 {
     uint16_t reset_count = 0;
@@ -748,6 +770,7 @@ void Attendance_ResetFailedRecords(void)
   * @param  index 记录索引
   * @retval 记录指针，如果索引无效则返回NULL
   */
+/* 函数作用：根据数组索引返回对应考勤记录指针。 */
 AttendanceRecord* Attendance_GetRecordByIndex(uint16_t index)
 {
     if (index < record_count)