1. 项目背景与目标

1.1 项目背景

在快节奏的现代生活中，高效管理个人时间和事务变得至关重要。虽然市面上有许多日程管理或笔记应用，但往往功能过于臃肿。为了满足本人对轻量级、集成化个性化移动办公工具的需求，本项目 Kali Mobile Dashboard 应运而生。

1.2 项目目标

本项目旨在构建一个基于 Flutter 的跨平台移动应用，核心目标包括：

  • 日程管理：提供直观的课程表/日程表视图，支持多视图切换（极简、今日、本周、总表）。

  • 待办事项：集成高效的 Todo List，支持单日任务、每日循环任务及周期性任务。

  • 笔记记录：提供便捷的文本笔记功能，支持增删改查。

  • 多端适配：基于 Flutter 实现 Android 与桌面端（Windows/Linux）的代码复用（目前重点优化 Android 端）。

2. 技术栈说明

本项目采用现代化的移动开发技术栈，确保应用的高性能与可维护性：

  • 开发框架: Flutter (SDK ^3.11.0) - Google 开源的 UI 工具包，用于构建高性能跨平台应用。

  • 编程语言: Dart - 强类型、面向对象的编程语言，Flutter 的开发语言。

  • 状态管理: provider (^6.1.5) - 官方推荐的轻量级状态管理方案，用于管理日程、待办和笔记的全局状态。

  • 本地存储:

    • sqflite (^2.4.2): Android/iOS 端的 SQLite 数据库插件，用于持久化存储笔记和复杂数据。

    • shared_preferences (^2.5.4): 用于存储轻量级配置信息（如用户偏好设置）。

  • 构建工具: Gradle (Android 构建), Flutter CLI。

  • 其他依赖:

    • intl: 日期格式化与国际化。

    • google_fonts: 字体管理。

    • file_picker / image_picker: 文件与图片选择。

    • spreadsheet_decoder: Excel 文件解析（用于导入课程表等）。

3. 核心文件结构解析

项目遵循 Flutter 标准工程结构，代码组织清晰，模块化程度高。

3.1 目录结构概览

d:\VSC\Project\Aapp
├── android/                  # Android 原生工程目录
│   ├── build.gradle.kts      # 项目级构建配置（配置了阿里云镜像源）
│   ├── settings.gradle.kts   # Gradle 设置
│   └── app/                  # Android App 模块
│       └── src/main/AndroidManifest.xml # 应用清单文件
├── lib/                      # Flutter 核心代码目录
│   ├── main.dart             # 应用入口
│   ├── models/               # 数据模型层
│   │   ├── course.dart       # 课程/日程模型
│   │   ├── note.dart         # 笔记模型
│   │   └── todo.dart         # 待办事项模型
│   ├── providers/            # 状态管理层 (ViewModel)
│   │   ├── note_provider.dart
│   │   ├── schedule_provider.dart
│   │   └── todo_provider.dart
│   ├── screens/              # UI 视图层
│   │   ├── home_screen.dart  # 主页框架（底部导航）
│   │   ├── schedule_screen.dart # 日程表页面
│   │   ├── todo_screen.dart     # 待办事项页面
│   │   └── notes_screen.dart    # 笔记列表页面
│   ├── services/             # 业务服务层
│   │   └── db_helper.dart    # 数据库操作封装
│   ├── utils/                # 工具类
│   │   └── constants.dart    # 全局常量
│   └── widgets/              # 公共组件
│       └── terminal_card.dart # 特色 UI 组件
└── pubspec.yaml              # 项目依赖配置文件

3.2 关键文件职责与代码展示

  1. lib/main.dart:

    • 职责: 程序的入口点。负责初始化 Flutter 绑定，设置全局 Provider（状态注入），并配置应用的主题和路由。

    • 代码展示:

      void main() {
  // 桌面端数据库初始化逻辑（目前为解决 Android 构建问题暂时注释）
  // if (Platform.isWindows || Platform.isLinux) {
  //   sqfliteFfiInit();
  //   databaseFactory = databaseFactoryFfi;
  // }
  WidgetsFlutterBinding.ensureInitialized();
  runApp(
    MultiProvider(
      providers: [
        ChangeNotifierProvider(create: (_) => TodoProvider()..loadTodos()),
        ChangeNotifierProvider(create: (_) => NoteProvider()..loadNotes()),
        ChangeNotifierProvider(create: (_) => ScheduleProvider()..loadSettings()),
      ],
      child: const MyApp(),
    ),
  );
}

  2. lib/services/db_helper.dart:

    • 职责: 单例模式的数据库助手类。负责创建数据库表结构，提供统一的增删改查接口，隔离上层业务逻辑与底层 SQL 实现。

    • 代码展示:

      class DBHelper {
  static final DBHelper _instance = DBHelper._internal();
  static Database? _database;

  factory DBHelper() => _instance;

  Future<Database> get database async {
    if (_database != null) return _database!;
    _database = await _initDatabase();
    return _database!;
  }

  Future<Database> _initDatabase() async {
    String path = join(await getDatabasesPath(), 'kali_dashboard.db');
    return await openDatabase(
      path,
      version: 1,
      onCreate: _onCreate,
    );
  }
  
  // 创建表结构
  Future<void> _onCreate(Database db, int version) async {
    await db.execute('''
      CREATE TABLE todos(
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        content TEXT,
        status INTEGER,
        category TEXT,
        target_date TEXT,
        priority INTEGER,
        created_at TEXT
      )
    ''');
    // ... notes table creation
  }
}

  3. lib/providers/schedule_provider.dart:

    • 职责: 管理课程数据的加载、解析和视图状态（当前周数、显示模式）。

    • 代码展示:

      class ScheduleProvider with ChangeNotifier {
  // 计算当前周数
  int get currentWeek {
    if (_semesterStart == null) return 1;
    final now = DateTime.now();
    final diff = now.difference(_semesterStart!).inDays;
    if (diff < 0) return 0; // Not started
    return (diff / 7).floor() + 1;
  }

  // 获取今日课程
  List<Course> getTodayCourses() {
    final now = DateTime.now();
    final week = currentWeek;
    final day = now.weekday; 
    
    if (day > 5) return []; // 周末处理

    return CourseData.allCourses.where((c) {
      return c.day == day && c.weeks.contains(week);
    }).toList();
  }
}

  4. android/build.gradle.kts:

    • 职责: Android 构建脚本。

    • 关键点: 修改了仓库源配置，添加了阿里云镜像（Maven Aliyun），解决了国内环境下的依赖下载超时问题。

    • 代码展示:

      allprojects {
    repositories {
        maven { url = uri("https://maven.aliyun.com/repository/public") }
        maven { url = uri("https://maven.aliyun.com/repository/google") }
        maven { url = uri("https://maven.aliyun.com/repository/gradle-plugin") }
        google()
        mavenCentral()
    }
}

4. 关键功能实现思路

4.1 动态日程表

通过 ScheduleProvider 管理课程数据。UI 层使用 GridView 或自定义 Stack 布局来绘制课程表网格。利用 provider 监听周数变化，动态过滤并显示当前周的课程。支持从 Excel 文件导入课程数据，通过 spreadsheet_decoder 解析表格内容并转换为 Course 模型对象。

4.2 待办事项管理

TodoProvider 维护待办列表。数据结构设计上，Todo 模型包含 date（日期）、isRepeat（是否每日重复）等字段。在显示逻辑上，根据当前选中的日期，筛选出“当天的单次任务”以及“所有每日重复任务”进行展示。

4.3 本地数据持久化

使用 sqflite 创建 SQLite 数据库。在应用启动时初始化数据库，若表不存在则自动创建。通过异步方法（Future）读写数据，避免阻塞 UI 线程，保证应用流畅度。

5. 开发过程中遇到的问题与解决方案

在开发和打包 APK 的过程中，遇到了一些典型的环境与构建问题，以下是详细记录与解决方案：

5.1 Gradle 依赖下载超时

  • 问题描述: org.gradle.internal.resolve.ArtifactResolveException: Could not download junit-jupiter-engine...。在构建过程中，Gradle 无法从 Google 和 Maven Central 下载依赖包。

  • 原因分析: 国内网络环境连接官方仓库不稳定。

  • 解决方案: 在 android/build.gradle.kts 和 android/settings.gradle.kts 中配置阿里云镜像源：

    maven { url = uri("https://maven.aliyun.com/repository/public") }
maven { url = uri("https://maven.aliyun.com/repository/google") }
maven { url = uri("https://maven.aliyun.com/repository/gradle-plugin") }

5.2 插件任务创建失败 (Roots different)

  • 问题描述: Could not create task ... this and base files have different roots。

  • 原因分析: 构建缓存路径与当前项目路径不一致，或者是 Gradle 缓存损坏。

  • 解决方案: 执行 flutter clean 清理构建缓存，然后重新运行 flutter pub get 和构建命令。

5.3 桌面端数据库依赖冲突

  • 问题描述: Execution failed for task ':app:compileFlutterBuildDebug'. 打包 Android 版本时，由于 sqflite_common_ffi（主要用于桌面端）的某些原生库下载失败或配置不兼容，导致构建中断。

  • 解决方案:

    1. 在 pubspec.yaml 中暂时注释掉 sqflite_common_ffi。

    2. 在 lib/main.dart 中注释掉针对 Windows/Linux 平台的数据库初始化代码 (sqfliteFfiInit)。

    3. 优先保证 Android 端的构建发布。

6. 总结与展望

6.1 总结

本项目成功实现了一个功能完备的移动端仪表盘应用。通过 Flutter 框架，高效地构建了美观且流畅的用户界面。

6.2 展望

  • 桌面端完善: 恢复并修复 sqflite_common_ffi 的配置，实现 Windows 和 Linux 端的完美支持，打通多端数据同步。

  • 功能扩展: 增加云同步功能，支持多设备间的数据实时同步。

  • UI 优化: 引入更丰富的动画效果和主题切换功能，还有UI设计，提升用户体验。

  • 修复BUG

7.项目文件

app-release.apk