终版

src/RecordListModel.h

@@ -9,11 +9,14 @@
 #include <QVariant>
 #include <QVector>
 
+// 考勤记录表格模型。QML 的 ListView/Table-like 布局通过 role 名称读取每列数据，
+// C++ 侧保留强类型 Item，避免界面层直接处理 QVariantMap。
 class RecordListModel : public QAbstractListModel
 {
     Q_OBJECT
 
 public:
+    // roleNames() 会把这些枚举映射为 timestamp、studentId、confidenceText 等 QML 字段。
     enum Roles {
         TimestampRole = Qt::UserRole + 1,
         ClassIdRole,
@@ -27,12 +30,17 @@ public:
         SuccessRole
     };
 
+    // 函数作用：创建考勤记录列表模型实例，并准备给 QML 使用的字段角色。
     explicit RecordListModel(QObject *parent = nullptr);
 
+    // 函数作用：返回当前显示的考勤记录行数。
     int rowCount(const QModelIndex &parent = QModelIndex()) const override;
+    // 函数作用：根据行号和角色返回考勤时间、学号、姓名、班级、置信度和状态等字段。
     QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
+    // 函数作用：提供 QML 读取考勤记录字段所需的 role 名称映射。
     QHash<int, QByteArray> roleNames() const override;
 
+    // Item 是已经完成映射后的显示数据：学号、姓名、班级名都由 AppController 处理好。
     struct Item {
         QString timestamp;
         QString classId;
@@ -44,6 +52,7 @@ public:
         bool success = false;
     };
 
+    // 函数作用：整体替换当前显示的考勤记录列表，并通知视图刷新。
     void setItems(const QVector<Item> &items);
 
 private: