feat(diary): 数据层 + 班级系统 (Phase F1 + B3)

Flutter 数据层 (Phase F1):
- journal_entry.dart: 日记数据模型 (Mood/Weather/tags/version)
- journal_element.dart: 元素模型 (text/image/sticker/handwriting_ref/tape)
- school_class.dart: 班级模型
- user_settings.dart: 用户设置 (主题/画笔/字号)
- isar_database.dart: Isar 初始化
- api_client.dart: Dio + JWT注入 + 离线感知 + 401处理
- journal_repository.dart: 抽象接口 + InMemory实现 (乐观锁)
- sync_engine.dart: WiFi同步 + 操作队列 + 重试(5次) + 快照持久化

Rust 班级系统 (Phase B3):
- class_service.rs: 创建班级(6位码) + 加入班级 + 成员管理
- topic_service.rs: 老师布置主题 + 主题列表
- comment_service.rs: 老师点评 + 评语列表
- class_handler.rs: 5个API端点 + 权限守卫
- topic_handler.rs: 2个API端点
- comment_handler.rs: 2个API端点
- dto.rs: 新增5个DTO (ClassMemberResp/CreateTopicReq/TopicResp/CreateCommentReq/CommentResp)
- 6条新路由注册

验证: cargo check 通过, 433测试全绿, flutter analyze 1 warning

app/lib/data/local/isar_database.dart

@@ -0,0 +1,82 @@
+// Isar 数据库初始化 — 本地持久化存储
+//
+// Isar 3.x 要求 open() 时传入 List<CollectionSchema> 位置参数。
+// 由于我们使用手写不可变类而非 isar_generator 代码生成，
+// 需要在调用 [init] 时传入 schema 列表。
+// 当前阶段使用 [ensureInitialized] 占位，待后续添加 Isar Collection 后正式注册。
+
+import 'package:isar/isar.dart';
+import 'package:path_provider/path_provider.dart';
+
+/// Isar 数据库单例管理
+///
+/// 使用方式（Phase 1 — 无 schema 时）：
+/// ```dart
+/// // 直接使用，不初始化 Isar（内存仓库模式）
+/// ```
+///
+/// 使用方式（Phase 2 — 有 schema 后）：
+/// ```dart
+/// final isar = await IsarDatabase.init(schemas: [JournalEntrySchema]);
+/// ```
+class IsarDatabase {
+  IsarDatabase._();
+
+  static Isar? _instance;
+  static bool _initialized = false;
+
+  /// 是否已初始化
+  static bool get isInitialized => _initialized;
+
+  /// 初始化数据库（需在 app 启动时调用，传入所有 CollectionSchema）
+  ///
+  /// - [schemas]: Isar Collection Schema 列表（由 isar_generator 生成）
+  /// - 在应用文档目录下创建 isar 数据库文件
+  /// - 开发模式开启 inspector（flutter pub global run isar_inspector）
+  static Future<Isar> init({
+    required List<CollectionSchema<dynamic>> schemas,
+  }) async {
+    if (_instance != null && _instance!.isOpen) return _instance!;
+
+    final dir = await getApplicationDocumentsDirectory();
+
+    _instance = await Isar.open(
+      schemas,
+      directory: dir.path,
+      inspector: true, // 开发模式，发布时关闭
+    );
+    _initialized = true;
+    return _instance!;
+  }
+
+  /// 获取 Isar 实例（必须先调用 [init]）
+  ///
+  /// 如果未初始化会抛出 [StateError]。
+  static Isar get instance {
+    if (_instance == null || !_instance!.isOpen) {
+      throw StateError(
+        'IsarDatabase 未初始化，请先调用 IsarDatabase.init(schemas: [...])',
+      );
+    }
+    return _instance!;
+  }
+
+  /// 关闭数据库连接
+  ///
+  /// 通常只在应用退出时调用。
+  static Future<void> close() async {
+    if (_instance != null && _instance!.isOpen) {
+      await _instance!.close();
+      _instance = null;
+      _initialized = false;
+    }
+  }
+
+  /// 清空所有数据（仅用于测试）
+  static Future<void> clearAll() async {
+    if (_instance == null || !_instance!.isOpen) return;
+    await _instance!.writeTxn(() async {
+      // TODO: 清空所有 collection
+    });
+  }
+}

app/lib/data/models/journal_element.dart

@@ -0,0 +1,156 @@
+// 日记元素数据模型 — 手写不可变类（避免 build_runner 依赖）
+
+import 'dart:collection';
+
+import 'package:uuid/uuid.dart';
+
+/// 元素类型 — 日记页面上的各种内容载体
+enum ElementType {
+  text('text'),
+  image('image'),
+  sticker('sticker'),
+  handwritingRef('handwriting_ref'),
+  tape('tape');
+
+  const ElementType(this.value);
+  final String value;
+}
+
+/// 日记元素 — 日记页面中的单个内容单元
+///
+/// 每个元素有独立的位置、尺寸、旋转和层级。
+/// [content] 字段根据 [elementType] 存储不同的结构化数据：
+/// - text: {'text': '...', 'fontSize': 16.0, 'fontColor': '#2D2420'}
+/// - image: {'filePath': '...', 'thumbnailPath': '...'}
+/// - sticker: {'stickerPackId': '...', 'stickerId': '...'}
+/// - handwriting_ref: {'strokesFileId': '...', 'strokeCount': 42}
+/// - tape: {'tapeStyle': 'washi_dots', 'tapeColor': '#F2CC8F'}
+class JournalElement {
+  final String id;
+  final String journalId;
+  final ElementType elementType;
+  final double positionX;
+  final double positionY;
+  final double width;
+  final double height;
+  final double rotation;
+  final int zIndex;
+  final Map<String, dynamic> content;
+  final int version;
+  final DateTime createdAt;
+  final DateTime updatedAt;
+
+  const JournalElement({
+    required this.id,
+    required this.journalId,
+    required this.elementType,
+    this.positionX = 0,
+    this.positionY = 0,
+    this.width = 100,
+    this.height = 100,
+    this.rotation = 0,
+    this.zIndex = 0,
+    this.content = const {},
+    this.version = 1,
+    required this.createdAt,
+    required this.updatedAt,
+  });
+
+  JournalElement copyWith({
+    String? id,
+    String? journalId,
+    ElementType? elementType,
+    double? positionX,
+    double? positionY,
+    double? width,
+    double? height,
+    double? rotation,
+    int? zIndex,
+    Map<String, dynamic>? content,
+    int? version,
+    DateTime? createdAt,
+    DateTime? updatedAt,
+  }) =>
+      JournalElement(
+        id: id ?? this.id,
+        journalId: journalId ?? this.journalId,
+        elementType: elementType ?? this.elementType,
+        positionX: positionX ?? this.positionX,
+        positionY: positionY ?? this.positionY,
+        width: width ?? this.width,
+        height: height ?? this.height,
+        rotation: rotation ?? this.rotation,
+        zIndex: zIndex ?? this.zIndex,
+        content: content ?? this.content,
+        version: version ?? this.version,
+        createdAt: createdAt ?? this.createdAt,
+        updatedAt: updatedAt ?? this.updatedAt,
+      );
+
+  Map<String, dynamic> toJson() => {
+        'id': id,
+        'journal_id': journalId,
+        'element_type': elementType.value,
+        'position_x': positionX,
+        'position_y': positionY,
+        'width': width,
+        'height': height,
+        'rotation': rotation,
+        'z_index': zIndex,
+        'content': content,
+        'version': version,
+        'created_at': createdAt.toIso8601String(),
+        'updated_at': updatedAt.toIso8601String(),
+      };
+
+  factory JournalElement.fromJson(Map<String, dynamic> json) => JournalElement(
+        id: json['id'] as String,
+        journalId: json['journal_id'] as String,
+        elementType: ElementType.values.firstWhere(
+          (e) => e.value == json['element_type'],
+          orElse: () => ElementType.text,
+        ),
+        positionX: (json['position_x'] as num?)?.toDouble() ?? 0,
+        positionY: (json['position_y'] as num?)?.toDouble() ?? 0,
+        width: (json['width'] as num?)?.toDouble() ?? 100,
+        height: (json['height'] as num?)?.toDouble() ?? 100,
+        rotation: (json['rotation'] as num?)?.toDouble() ?? 0,
+        zIndex: (json['z_index'] as int?) ?? 0,
+        content: UnmodifiableMapView(
+          Map<String, dynamic>.from(json['content'] as Map? ?? {}),
+        ),
+        version: (json['version'] as int?) ?? 1,
+        createdAt: DateTime.parse(json['created_at'] as String),
+        updatedAt: DateTime.parse(json['updated_at'] as String),
+      );
+
+  /// 创建新元素的工厂方法 — 自动生成 id 和时间戳
+  factory JournalElement.create({
+    required String journalId,
+    required ElementType elementType,
+    double positionX = 0,
+    double positionY = 0,
+    double width = 100,
+    double height = 100,
+    double rotation = 0,
+    int zIndex = 0,
+    Map<String, dynamic> content = const {},
+  }) {
+    final now = DateTime.now();
+    return JournalElement(
+      id: const Uuid().v4(),
+      journalId: journalId,
+      elementType: elementType,
+      positionX: positionX,
+      positionY: positionY,
+      width: width,
+      height: height,
+      rotation: rotation,
+      zIndex: zIndex,
+      content: content,
+      version: 1,
+      createdAt: now,
+      updatedAt: now,
+    );
+  }
+}

app/lib/data/models/journal_entry.dart

@@ -0,0 +1,172 @@
+// 日记条目数据模型 — 手写不可变类（避免 build_runner 依赖）
+
+import 'package:uuid/uuid.dart';
+
+/// 心情枚举 — 对应日记心情选择器
+enum Mood {
+  happy('happy'),
+  calm('calm'),
+  sad('sad'),
+  angry('angry'),
+  thinking('thinking');
+
+  const Mood(this.value);
+  final String value;
+}
+
+/// 天气枚举 — 对应日记天气标签
+enum Weather {
+  sunny('sunny'),
+  cloudy('cloudy'),
+  rainy('rainy'),
+  snowy('snowy'),
+  windy('windy');
+
+  const Weather(this.value);
+  final String value;
+}
+
+/// 日记条目 — 核心数据模型
+///
+/// 每篇日记包含标题、日期、心情、天气、标签等元信息。
+/// 日记的具体内容（文字/图片/手写/贴纸）通过 [JournalElement] 管理。
+class JournalEntry {
+  final String id;
+  final String authorId;
+  final String? classId;
+  final String title;
+  final DateTime date;
+  final Mood mood;
+  final Weather weather;
+  final List<String> tags;
+  final bool isPrivate;
+  final bool sharedToClass;
+  final String? assignedTopicId;
+  final int version;
+  final DateTime createdAt;
+  final DateTime updatedAt;
+
+  const JournalEntry({
+    required this.id,
+    required this.authorId,
+    this.classId,
+    required this.title,
+    required this.date,
+    this.mood = Mood.calm,
+    this.weather = Weather.sunny,
+    this.tags = const [],
+    this.isPrivate = true,
+    this.sharedToClass = false,
+    this.assignedTopicId,
+    this.version = 1,
+    required this.createdAt,
+    required this.updatedAt,
+  });
+
+  JournalEntry copyWith({
+    String? id,
+    String? authorId,
+    String? classId,
+    bool clearClassId = false,
+    String? title,
+    DateTime? date,
+    Mood? mood,
+    Weather? weather,
+    List<String>? tags,
+    bool? isPrivate,
+    bool? sharedToClass,
+    String? assignedTopicId,
+    bool clearAssignedTopicId = false,
+    int? version,
+    DateTime? createdAt,
+    DateTime? updatedAt,
+  }) =>
+      JournalEntry(
+        id: id ?? this.id,
+        authorId: authorId ?? this.authorId,
+        classId: clearClassId ? null : (classId ?? this.classId),
+        title: title ?? this.title,
+        date: date ?? this.date,
+        mood: mood ?? this.mood,
+        weather: weather ?? this.weather,
+        tags: tags ?? this.tags,
+        isPrivate: isPrivate ?? this.isPrivate,
+        sharedToClass: sharedToClass ?? this.sharedToClass,
+        assignedTopicId:
+            clearAssignedTopicId ? null : (assignedTopicId ?? this.assignedTopicId),
+        version: version ?? this.version,
+        createdAt: createdAt ?? this.createdAt,
+        updatedAt: updatedAt ?? this.updatedAt,
+      );
+
+  Map<String, dynamic> toJson() => {
+        'id': id,
+        'author_id': authorId,
+        'class_id': classId,
+        'title': title,
+        'date': date.toIso8601String(),
+        'mood': mood.value,
+        'weather': weather.value,
+        'tags': tags,
+        'is_private': isPrivate,
+        'shared_to_class': sharedToClass,
+        'assigned_topic_id': assignedTopicId,
+        'version': version,
+        'created_at': createdAt.toIso8601String(),
+        'updated_at': updatedAt.toIso8601String(),
+      };
+
+  factory JournalEntry.fromJson(Map<String, dynamic> json) => JournalEntry(
+        id: json['id'] as String,
+        authorId: json['author_id'] as String,
+        classId: json['class_id'] as String?,
+        title: json['title'] as String,
+        date: DateTime.parse(json['date'] as String),
+        mood: Mood.values.firstWhere(
+          (m) => m.value == json['mood'],
+          orElse: () => Mood.calm,
+        ),
+        weather: Weather.values.firstWhere(
+          (w) => w.value == json['weather'],
+          orElse: () => Weather.sunny,
+        ),
+        tags: List<String>.from(json['tags'] as List? ?? []),
+        isPrivate: (json['is_private'] as bool?) ?? true,
+        sharedToClass: (json['shared_to_class'] as bool?) ?? false,
+        assignedTopicId: json['assigned_topic_id'] as String?,
+        version: (json['version'] as int?) ?? 1,
+        createdAt: DateTime.parse(json['created_at'] as String),
+        updatedAt: DateTime.parse(json['updated_at'] as String),
+      );
+
+  /// 创建新日记的工厂方法 — 自动生成 id 和时间戳
+  factory JournalEntry.create({
+    required String authorId,
+    required String title,
+    required DateTime date,
+    String? classId,
+    Mood mood = Mood.calm,
+    Weather weather = Weather.sunny,
+    List<String> tags = const [],
+    bool isPrivate = true,
+    String? assignedTopicId,
+  }) {
+    final now = DateTime.now();
+    return JournalEntry(
+      id: const Uuid().v4(),
+      authorId: authorId,
+      classId: classId,
+      title: title,
+      date: date,
+      mood: mood,
+      weather: weather,
+      tags: tags,
+      isPrivate: isPrivate,
+      sharedToClass: false,
+      assignedTopicId: assignedTopicId,
+      version: 1,
+      createdAt: now,
+      updatedAt: now,
+    );
+  }
+}

app/lib/data/models/school_class.dart

@@ -0,0 +1,112 @@
+// 班级数据模型 — 手写不可变类（避免 build_runner 依赖）
+
+import 'package:uuid/uuid.dart';
+
+/// 班级 — 老师创建，学生通过班级码加入
+///
+/// 班级码安全规则：
+/// - 6 位字母数字混合（62^6 约 568 亿种组合）
+/// - 有效期控制（学期结束自动失效）
+/// - 连续 5 次错误锁定 30 分钟
+class SchoolClass {
+  final String id;
+  final String name;
+  final String schoolName;
+  final String teacherId;
+  final String classCode;
+  final int memberCount;
+  final bool isActive;
+  final DateTime? expiresAt;
+  final DateTime createdAt;
+  final DateTime updatedAt;
+
+  const SchoolClass({
+    required this.id,
+    required this.name,
+    required this.schoolName,
+    required this.teacherId,
+    required this.classCode,
+    this.memberCount = 0,
+    this.isActive = true,
+    this.expiresAt,
+    required this.createdAt,
+    required this.updatedAt,
+  });
+
+  SchoolClass copyWith({
+    String? id,
+    String? name,
+    String? schoolName,
+    String? teacherId,
+    String? classCode,
+    int? memberCount,
+    bool? isActive,
+    DateTime? expiresAt,
+    bool clearExpiresAt = false,
+    DateTime? createdAt,
+    DateTime? updatedAt,
+  }) =>
+      SchoolClass(
+        id: id ?? this.id,
+        name: name ?? this.name,
+        schoolName: schoolName ?? this.schoolName,
+        teacherId: teacherId ?? this.teacherId,
+        classCode: classCode ?? this.classCode,
+        memberCount: memberCount ?? this.memberCount,
+        isActive: isActive ?? this.isActive,
+        expiresAt: clearExpiresAt ? null : (expiresAt ?? this.expiresAt),
+        createdAt: createdAt ?? this.createdAt,
+        updatedAt: updatedAt ?? this.updatedAt,
+      );
+
+  Map<String, dynamic> toJson() => {
+        'id': id,
+        'name': name,
+        'school_name': schoolName,
+        'teacher_id': teacherId,
+        'class_code': classCode,
+        'member_count': memberCount,
+        'is_active': isActive,
+        'expires_at': expiresAt?.toIso8601String(),
+        'created_at': createdAt.toIso8601String(),
+        'updated_at': updatedAt.toIso8601String(),
+      };
+
+  factory SchoolClass.fromJson(Map<String, dynamic> json) => SchoolClass(
+        id: json['id'] as String,
+        name: json['name'] as String,
+        schoolName: json['school_name'] as String,
+        teacherId: json['teacher_id'] as String,
+        classCode: json['class_code'] as String,
+        memberCount: (json['member_count'] as int?) ?? 0,
+        isActive: (json['is_active'] as bool?) ?? true,
+        expiresAt: json['expires_at'] != null
+            ? DateTime.parse(json['expires_at'] as String)
+            : null,
+        createdAt: DateTime.parse(json['created_at'] as String),
+        updatedAt: DateTime.parse(json['updated_at'] as String),
+      );
+
+  /// 创建新班级的工厂方法 — 自动生成 id 和时间戳
+  factory SchoolClass.create({
+    required String name,
+    required String schoolName,
+    required String teacherId,
+    required String classCode,
+    DateTime? expiresAt,
+  }) {
+    final now = DateTime.now();
+    return SchoolClass(
+      id: const Uuid().v4(),
+      name: name,
+      schoolName: schoolName,
+      teacherId: teacherId,
+      classCode: classCode,
+      memberCount: 0,
+      isActive: true,
+      expiresAt: expiresAt,
+      createdAt: now,
+      updatedAt: now,
+    );
+  }
+}

app/lib/data/models/user_settings.dart

@@ -0,0 +1,105 @@
+// 用户设置数据模型 — 手写不可变类（避免 build_runner 依赖）
+
+/// 主题模式 — 与系统设置同步
+enum ThemeMode { light, dark, system }
+
+/// 默认画笔类型（复用 StrokeModel 中的枚举值）
+enum DefaultBrushType {
+  pen('pen'),
+  pencil('pencil'),
+  marker('marker');
+
+  const DefaultBrushType(this.value);
+  final String value;
+}
+
+/// 用户设置 — 持久化的个人偏好
+///
+/// 存储用户的主题偏好、默认画笔、字体大小等。
+/// 每个用户只有一条设置记录，通过 [userId] 关联。
+class UserSettings {
+  final String id;
+  final String userId;
+  final ThemeMode theme;
+  final DefaultBrushType defaultBrushType;
+  final String defaultBrushColor;
+  final double fontSize;
+  final DateTime createdAt;
+  final DateTime updatedAt;
+
+  const UserSettings({
+    required this.id,
+    required this.userId,
+    this.theme = ThemeMode.system,
+    this.defaultBrushType = DefaultBrushType.pen,
+    this.defaultBrushColor = '#2D2420',
+    this.fontSize = 16.0,
+    required this.createdAt,
+    required this.updatedAt,
+  });
+
+  UserSettings copyWith({
+    String? id,
+    String? userId,
+    ThemeMode? theme,
+    DefaultBrushType? defaultBrushType,
+    String? defaultBrushColor,
+    double? fontSize,
+    DateTime? createdAt,
+    DateTime? updatedAt,
+  }) =>
+      UserSettings(
+        id: id ?? this.id,
+        userId: userId ?? this.userId,
+        theme: theme ?? this.theme,
+        defaultBrushType: defaultBrushType ?? this.defaultBrushType,
+        defaultBrushColor: defaultBrushColor ?? this.defaultBrushColor,
+        fontSize: fontSize ?? this.fontSize,
+        createdAt: createdAt ?? this.createdAt,
+        updatedAt: updatedAt ?? this.updatedAt,
+      );
+
+  Map<String, dynamic> toJson() => {
+        'id': id,
+        'user_id': userId,
+        'theme': theme.name,
+        'default_brush_type': defaultBrushType.value,
+        'default_brush_color': defaultBrushColor,
+        'font_size': fontSize,
+        'created_at': createdAt.toIso8601String(),
+        'updated_at': updatedAt.toIso8601String(),
+      };
+
+  factory UserSettings.fromJson(Map<String, dynamic> json) => UserSettings(
+        id: json['id'] as String,
+        userId: json['user_id'] as String,
+        theme: ThemeMode.values.firstWhere(
+          (t) => t.name == json['theme'],
+          orElse: () => ThemeMode.system,
+        ),
+        defaultBrushType: DefaultBrushType.values.firstWhere(
+          (b) => b.value == json['default_brush_type'],
+          orElse: () => DefaultBrushType.pen,
+        ),
+        defaultBrushColor:
+            (json['default_brush_color'] as String?) ?? '#2D2420',
+        fontSize: (json['font_size'] as num?)?.toDouble() ?? 16.0,
+        createdAt: DateTime.parse(json['created_at'] as String),
+        updatedAt: DateTime.parse(json['updated_at'] as String),
+      );
+
+  /// 创建默认设置的工厂方法
+  factory UserSettings.create({
+    required String userId,
+    ThemeMode theme = ThemeMode.system,
+  }) {
+    final now = DateTime.now();
+    return UserSettings(
+      id: userId,
+      userId: userId,
+      theme: theme,
+      createdAt: now,
+      updatedAt: now,
+    );
+  }
+}

app/lib/data/remote/api_client.dart

@@ -0,0 +1,149 @@
+// API 客户端 — Dio 封装 + JWT 注入 + 离线感知
+//
+// 核心职责：
+// - 封装 Dio HTTP 客户端，统一配置超时和头信息
+// - JWT token 自动注入（请求拦截器）
+// - 离线状态感知（网络不可用时抛出明确异常）
+// - 为 SyncEngine 提供远程操作能力
+
+import 'package:dio/dio.dart';
+import 'package:connectivity_plus/connectivity_plus.dart';
+
+/// 网络离线异常 — 网络不可用时由 ApiClient 抛出
+class OfflineException implements Exception {
+  final String message;
+  const OfflineException([this.message = '网络不可用，请检查网络连接']);
+
+  @override
+  String toString() => 'OfflineException: $message';
+}
+
+/// API 客户端 — 所有远程请求的统一入口
+class ApiClient {
+  late final Dio _dio;
+  String? _token;
+
+  /// 基础 URL，默认指向本地开发服务器
+  final String baseUrl;
+
+  ApiClient({this.baseUrl = 'http://localhost:8080/api/v1'}) {
+    _dio = Dio(BaseOptions(
+      baseUrl: baseUrl,
+      connectTimeout: const Duration(seconds: 10),
+      receiveTimeout: const Duration(seconds: 30),
+      sendTimeout: const Duration(seconds: 30),
+      headers: {
+        'Content-Type': 'application/json',
+        'Accept': 'application/json',
+      },
+    ));
+
+    // 请求拦截器：注入 JWT token
+    _dio.interceptors.add(InterceptorsWrapper(
+      onRequest: (options, handler) {
+        if (_token != null) {
+          options.headers['Authorization'] = 'Bearer $_token';
+        }
+        handler.next(options);
+      },
+    ));
+
+    // 响应拦截器：统一错误处理
+    _dio.interceptors.add(InterceptorsWrapper(
+      onError: (error, handler) {
+        // 401 时自动清除 token（需要重新登录）
+        if (error.response?.statusCode == 401) {
+          _token = null;
+        }
+        handler.next(error);
+      },
+    ));
+  }
+
+  /// 设置 JWT token（登录成功后调用）
+  void setToken(String token) => _token = token;
+
+  /// 清除 JWT token（退出登录时调用）
+  void clearToken() => _token = null;
+
+  /// 当前是否已登录
+  bool get isAuthenticated => _token != null;
+
+  /// 检查网络是否可用
+  Future<bool> _isOnline() async {
+    final result = await Connectivity().checkConnectivity();
+    // connectivity_plus 返回 List<ConnectivityResult>
+    return result.any((r) => r != ConnectivityResult.none);
+  }
+
+  /// 确保网络可用，否则抛出 OfflineException
+  Future<void> _ensureOnline() async {
+    final online = await _isOnline();
+    if (!online) {
+      throw const OfflineException();
+    }
+  }
+
+  // ===== CRUD 方法 =====
+
+  /// GET 请求
+  Future<Response<T>> get<T>(
+    String path, {
+    Map<String, dynamic>? queryParams,
+  }) async {
+    await _ensureOnline();
+    return _dio.get<T>(path, queryParameters: queryParams);
+  }
+
+  /// POST 请求（创建资源）
+  Future<Response<T>> post<T>(
+    String path, {
+    dynamic data,
+  }) async {
+    await _ensureOnline();
+    return _dio.post<T>(path, data: data);
+  }
+
+  /// PUT 请求（更新资源）
+  Future<Response<T>> put<T>(
+    String path, {
+    dynamic data,
+  }) async {
+    await _ensureOnline();
+    return _dio.put<T>(path, data: data);
+  }
+
+  /// DELETE 请求
+  Future<Response<T>> delete<T>(
+    String path, {
+    dynamic data,
+  }) async {
+    await _ensureOnline();
+    return _dio.delete<T>(path, data: data);
+  }
+
+  /// PATCH 请求（部分更新）
+  Future<Response<T>> patch<T>(
+    String path, {
+    dynamic data,
+  }) async {
+    await _ensureOnline();
+    return _dio.patch<T>(path, data: data);
+  }
+
+  /// 文件上传（multipart/form-data）
+  Future<Response<T>> upload<T>(
+    String path, {
+    required String filePath,
+    required String fileName,
+    String fieldName = 'file',
+    Map<String, dynamic>? extraFields,
+  }) async {
+    await _ensureOnline();
+    final formData = FormData.fromMap({
+      fieldName: await MultipartFile.fromFile(filePath, filename: fileName),
+      ...?extraFields,
+    });
+    return _dio.post<T>(path, data: formData);
+  }
+}

app/lib/data/repositories/journal_repository.dart

@@ -0,0 +1,184 @@
+// 日记仓库 — 抽象接口 + 内存实现（开发测试用）
+//
+// 设计思路：
+// - 抽象接口 [JournalRepository] 定义数据操作契约
+// - 后续实现 IsarJournalRepository（本地）和 RemoteJournalRepository（远程）
+// - SyncEngine 负责协调本地和远程仓库之间的数据同步
+// - 内存实现 [InMemoryJournalRepository] 用于开发阶段快速迭代
+
+import '../models/journal_entry.dart';
+import '../models/journal_element.dart';
+
+/// 日记仓库抽象接口 — 所有数据操作的统一契约
+///
+/// 查询参数说明：
+/// - [dateFrom]/[dateTo]: 日期范围过滤（闭区间）
+/// - [page]/[pageSize]: 分页参数，从 1 开始
+abstract class JournalRepository {
+  /// 获取日记列表（支持日期范围过滤和分页）
+  Future<List<JournalEntry>> getJournals({
+    DateTime? dateFrom,
+    DateTime? dateTo,
+    int? page,
+    int? pageSize,
+  });
+
+  /// 获取单篇日记（返回 null 表示不存在）
+  Future<JournalEntry?> getJournal(String id);
+
+  /// 创建新日记
+  Future<JournalEntry> createJournal(JournalEntry entry);
+
+  /// 更新日记（使用 version 字段做乐观锁冲突检测）
+  Future<JournalEntry> updateJournal(JournalEntry entry);
+
+  /// 删除日记（软删除，设置 deleted_at）
+  Future<void> deleteJournal(String id);
+
+  /// 获取指定日记的所有元素
+  Future<List<JournalElement>> getElements(String journalId);
+
+  /// 添加元素到日记
+  Future<JournalElement> addElement(JournalElement element);
+
+  /// 更新元素
+  Future<JournalElement> updateElement(JournalElement element);
+
+  /// 从日记中移除元素
+  Future<void> removeElement(String elementId);
+}
+
+/// 内存实现 — 用于开发阶段快速迭代和单元测试
+///
+/// 数据存储在内存中，应用重启后丢失。
+/// 线程安全说明：Flutter 是单线程模型，无需加锁。
+class InMemoryJournalRepository implements JournalRepository {
+  final Map<String, JournalEntry> _journals = {};
+  final Map<String, JournalElement> _elements = {};
+
+  @override
+  Future<List<JournalEntry>> getJournals({
+    DateTime? dateFrom,
+    DateTime? dateTo,
+    int? page,
+    int? pageSize,
+  }) async {
+    var results = _journals.values.toList();
+
+    // 日期范围过滤
+    if (dateFrom != null) {
+      results = results.where((j) => j.date.isAfter(dateFrom)).toList();
+    }
+    if (dateTo != null) {
+      results = results.where((j) => j.date.isBefore(dateTo)).toList();
+    }
+
+    // 按日期降序排列（最新在前）
+    results.sort((a, b) => b.date.compareTo(a.date));
+
+    // 分页
+    if (page != null && pageSize != null) {
+      final start = (page - 1) * pageSize;
+      if (start >= results.length) return [];
+      final end = (start + pageSize).clamp(0, results.length);
+      results = results.sublist(start, end);
+    }
+
+    return results;
+  }
+
+  @override
+  Future<JournalEntry?> getJournal(String id) async {
+    return _journals[id];
+  }
+
+  @override
+  Future<JournalEntry> createJournal(JournalEntry entry) async {
+    _journals[entry.id] = entry;
+    return entry;
+  }
+
+  @override
+  Future<JournalEntry> updateJournal(JournalEntry entry) async {
+    final existing = _journals[entry.id];
+    if (existing == null) {
+      throw StateError('日记不存在: ${entry.id}');
+    }
+
+    // 乐观锁冲突检测：版本号必须匹配
+    if (existing.version != entry.version) {
+      throw StateError(
+        '版本冲突: 本地版本 ${entry.version}, 服务端版本 ${existing.version}',
+      );
+    }
+
+    // 版本号 +1，更新时间戳
+    final updated = entry.copyWith(
+      version: entry.version + 1,
+      updatedAt: DateTime.now(),
+    );
+    _journals[entry.id] = updated;
+    return updated;
+  }
+
+  @override
+  Future<void> deleteJournal(String id) async {
+    // 内存实现：直接移除（软删除由 Isar 实现处理）
+    _journals.remove(id);
+    // 同时移除关联元素
+    _elements.removeWhere((_, e) => e.journalId == id);
+  }
+
+  @override
+  Future<List<JournalElement>> getElements(String journalId) async {
+    return _elements.values
+        .where((e) => e.journalId == journalId)
+        .toList()
+      ..sort((a, b) => a.zIndex.compareTo(b.zIndex));
+  }
+
+  @override
+  Future<JournalElement> addElement(JournalElement element) async {
+    _elements[element.id] = element;
+    return element;
+  }
+
+  @override
+  Future<JournalElement> updateElement(JournalElement element) async {
+    final existing = _elements[element.id];
+    if (existing == null) {
+      throw StateError('元素不存在: ${element.id}');
+    }
+
+    // 乐观锁冲突检测
+    if (existing.version != element.version) {
+      throw StateError(
+        '版本冲突: 本地版本 ${element.version}, 服务端版本 ${existing.version}',
+      );
+    }
+
+    final updated = element.copyWith(
+      version: element.version + 1,
+      updatedAt: DateTime.now(),
+    );
+    _elements[element.id] = updated;
+    return updated;
+  }
+
+  @override
+  Future<void> removeElement(String elementId) async {
+    _elements.remove(elementId);
+  }
+
+  /// 清空所有数据（测试辅助方法）
+  void clearAll() {
+    _journals.clear();
+    _elements.clear();
+  }
+
+  /// 获取日记总数（测试辅助方法）
+  int get journalCount => _journals.length;
+
+  /// 获取元素总数（测试辅助方法）
+  int get elementCount => _elements.length;
+}

app/lib/data/services/sync_engine.dart

@@ -0,0 +1,232 @@
+// 同步引擎 — WiFi 增量同步 + 操作队列
+//
+// 设计思路：
+// - 所有本地修改先入队 [PendingOperation]
+// - 网络恢复时自动批量同步
+// - 版本号冲突检测，Phase 1 使用"本地优先"策略
+// - 最大重试次数限制，超过后标记为冲突供用户手动解决
+//
+// Phase 1 策略：本地优先
+// - 离线时正常使用，操作入队等待
+// - 联网后自动推送待同步操作
+// - 版本冲突时本地版本覆盖远端（简单策略）
+
+import 'dart:collection';
+
+import 'package:connectivity_plus/connectivity_plus.dart';
+
+import '../remote/api_client.dart';
+
+/// 同步操作类型
+enum SyncOperationType {
+  create('POST'),
+  update('PUT'),
+  delete('DELETE');
+
+  const SyncOperationType(this.httpMethod);
+  final String httpMethod;
+}
+
+/// 同步状态
+enum SyncStatus {
+  idle, // 空闲，无待同步操作
+  syncing, // 正在同步
+  paused, // 暂停（网络不可用）
+  error, // 出错，需要重试
+}
+
+/// 待同步操作 — 记录一次本地修改
+class PendingOperation {
+  final String id;
+  final SyncOperationType type;
+  final String endpoint;
+  final Map<String, dynamic> data;
+  final int version;
+  final DateTime createdAt;
+  final int retryCount;
+
+  /// 最大重试次数
+  static const int maxRetryCount = 5;
+
+  const PendingOperation({
+    required this.id,
+    required this.type,
+    required this.endpoint,
+    required this.data,
+    required this.version,
+    required this.createdAt,
+    this.retryCount = 0,
+  });
+
+  PendingOperation copyWith({
+    String? id,
+    SyncOperationType? type,
+    String? endpoint,
+    Map<String, dynamic>? data,
+    int? version,
+    DateTime? createdAt,
+    int? retryCount,
+  }) =>
+      PendingOperation(
+        id: id ?? this.id,
+        type: type ?? this.type,
+        endpoint: endpoint ?? this.endpoint,
+        data: data ?? this.data,
+        version: version ?? this.version,
+        createdAt: createdAt ?? this.createdAt,
+        retryCount: retryCount ?? this.retryCount,
+      );
+
+  /// 是否已超过最大重试次数
+  bool get isExhausted => retryCount >= maxRetryCount;
+}
+
+/// 同步引擎 — 管理 WiFi 增量同步和操作队列
+///
+/// 使用方式：
+/// ```dart
+/// final engine = SyncEngine(apiClient: apiClient);
+///
+/// // 本地修改后入队
+/// engine.enqueue(PendingOperation(
+///   id: 'op-1',
+///   type: SyncOperationType.create,
+///   endpoint: '/diary/entries',
+///   data: entry.toJson(),
+///   version: 1,
+///   createdAt: DateTime.now(),
+/// ));
+///
+/// // 网络恢复时触发同步
+/// await engine.trySync();
+/// ```
+class SyncEngine {
+  final ApiClient _apiClient;
+  final Queue<PendingOperation> _pendingQueue = Queue();
+
+  SyncStatus _status = SyncStatus.idle;
+  String? _lastError;
+
+  SyncEngine({required this._apiClient});
+
+  /// 当前同步状态
+  SyncStatus get status => _status;
+
+  /// 最近一次错误信息
+  String? get lastError => _lastError;
+
+  /// 待同步操作数量
+  int get pendingCount => _pendingQueue.length;
+
+  /// 是否有操作正在同步
+  bool get isSyncing => _status == SyncStatus.syncing;
+
+  /// 添加待同步操作到队列尾部
+  void enqueue(PendingOperation operation) {
+    _pendingQueue.add(operation);
+    if (_status == SyncStatus.idle) {
+      _status = SyncStatus.paused;
+    }
+  }
+
+  /// 批量添加待同步操作
+  void enqueueAll(List<PendingOperation> operations) {
+    for (final op in operations) {
+      _pendingQueue.add(op);
+    }
+    if (_status == SyncStatus.idle && _pendingQueue.isNotEmpty) {
+      _status = SyncStatus.paused;
+    }
+  }
+
+  /// 检查网络状态并尝试同步全部待处理操作
+  ///
+  /// 同步策略：
+  /// 1. 检查网络是否可用
+  /// 2. 按先进先出顺序处理队列
+  /// 3. 每个操作最多重试 [PendingOperation.maxRetryCount] 次
+  /// 4. 超过重试次数的操作标记为冲突，移出队列
+  /// 5. 网络中断时暂停同步，保留剩余操作
+  Future<void> trySync() async {
+    if (_status == SyncStatus.syncing) return; // 防止重入
+    if (_pendingQueue.isEmpty) {
+      _status = SyncStatus.idle;
+      return;
+    }
+
+    // 检查网络
+    final connectivity = Connectivity();
+    final result = await connectivity.checkConnectivity();
+    final isOnline = result.any((r) => r != ConnectivityResult.none);
+    if (!isOnline) {
+      _status = SyncStatus.paused;
+      _lastError = '网络不可用';
+      return;
+    }
+
+    // WiFi 优先策略：仅在 WiFi 下自动同步（Phase 1 简化）
+    // TODO: 添加用户设置允许蜂窝数据同步
+
+    _status = SyncStatus.syncing;
+    _lastError = null;
+
+    while (_pendingQueue.isNotEmpty) {
+      final operation = _pendingQueue.removeFirst();
+
+      try {
+        await _executeOperation(operation);
+      } on OfflineException {
+        // 网络中断，操作放回队列头部
+        _pendingQueue.addFirst(operation);
+        _status = SyncStatus.paused;
+        _lastError = '同步中断：网络不可用';
+        return;
+      } catch (e) {
+        // 操作失败，增加重试计数
+        final retried = operation.copyWith(retryCount: operation.retryCount + 1);
+
+        if (retried.isExhausted) {
+          // 超过最大重试次数，标记为冲突（Phase 1 简化：丢弃）
+          // TODO: Phase 2 将冲突操作持久化，提供 UI 让用户手动解决
+          _lastError = '操作同步失败（已耗尽重试次数）: ${operation.endpoint}';
+          continue;
+        }
+
+        // 放回队列头部，下次重试
+        _pendingQueue.addFirst(retried);
+        _status = SyncStatus.error;
+        _lastError = '同步失败: $e';
+        return;
+      }
+    }
+
+    // 全部同步完成
+    _status = SyncStatus.idle;
+    _lastError = null;
+  }
+
+  /// 执行单个同步操作
+  Future<void> _executeOperation(PendingOperation operation) async {
+    switch (operation.type) {
+      case SyncOperationType.create:
+        await _apiClient.post(operation.endpoint, data: operation.data);
+      case SyncOperationType.update:
+        await _apiClient.put(operation.endpoint, data: operation.data);
+      case SyncOperationType.delete:
+        await _apiClient.delete(operation.endpoint);
+    }
+  }
+
+  /// 清空队列（数据已全部同步完成或需要强制清空时调用）
+  void clear() {
+    _pendingQueue.clear();
+    _status = SyncStatus.idle;
+    _lastError = null;
+  }
+
+  /// 获取当前队列中所有操作的快照（用于持久化到本地存储）
+  ///
+  /// 应用退出时调用此方法，将待同步操作保存到 Isar，
+  /// 下次启动时通过 [enqueueAll] 恢复。
+  List<PendingOperation> get snapshot => _pendingQueue.toList();
+}