Skip to content
pingg241Public

About

为四川大学专门定制的课程表查看软件,同时可以较为轻松的修改为任意学校的专用课程表

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Kelo

Kelo 是一个面向学生日常使用的轻量课表应用,当前重点支持 Android 和 Windows。应用以本地优先为核心,支持离线查看课表、本地编辑、多课表管理、教务系统导入,以及本地数据导出/导入。

当前能力

  • 查看当前教学周、今天日期、下一节课和今日课程。
  • 查看完整周课表。
  • 本地添加、编辑、删除课程。
  • 支持多套课表管理。
  • 支持设置当前教学周和总周数。
  • 支持四川大学教务系统登录并导入课表。
  • 教务接入采用学校适配器结构,可新增其他学校实现。
  • 支持 JSON 备份导出和导入。
  • 支持浅色/深色/跟随系统主题和主题色配置。
  • 支持 Android 和 Windows 桌面布局。

技术栈

  • Flutter + Material 3
  • Riverpod 代码生成风格
  • drift + SQLite
  • Flutter gen_l10n + ARB
  • shared_preferences
  • dio
  • file_manager / file_selector

项目结构

lib/
  main.dart
  app/
    app.dart                  # MaterialApp、主题、l10n 入口
    l10n/                     # ARB 与生成的本地化代码
    shell/                    # 移动/桌面导航外壳
    theme/                    # 主题、颜色、字体和主题控制器
  core/
    constants/                # 全局布局常量
    time/                     # 学期周计算、节次时间等时间逻辑
  features/
    auth/
      application/            # 教务登录、导入状态控制
      data/                   # 通用教务请求、本地会话和学校适配器
        universities/        # 每所学校独立的登录与课表协议实现
      model/                  # 登录会话、验证码、教务课表模型
      presentation/           # 教务登录页
    backup/
      application/            # 备份导入/导出状态
      data/                   # 备份 JSON 编码、文件读写
      model/                  # 备份文档模型
      presentation/           # 数据备份页面和 Android 文件选择
    schedule/
      application/            # 课表状态、筛选、下一节课计算
      data/                   # drift 数据库、本地数据源、Repository
      model/                  # 课程、学期、多课表模型
      presentation/
        layouts/              # 移动/桌面课表布局
        widgets/              # 周课表网格、课程卡片、详情、管理弹窗
    settings/
      presentation/           # 设置入口、外观、关于等页面
  shared/
    presentation/             # 多 feature 复用的展示组件

test/
  app/
  core/
  features/

添加其他学校教务系统

不同学校的登录页面、密码算法、接口字段、课表格式和节次时间通常并不相同。Kelo 不要求学校实现服从同一套 JSON 配置,而是通过 UniversityAdapter 将学校协议转换成应用统一模型。

1. 创建学校目录

lib/features/auth/data/universities/example_university/
  example_university_adapter.dart
  example_university_profile.dart
  example_login_parser.dart
  example_password_codec.dart
  example_schedule_parser.dart
  example_schedule_response.dart

学校专属的 URL、页面关键字、加密盐值、原始响应字段、校区名称和作息表必须放在该目录,不要写入通用 AuthApi、Controller 或课表 Widget。

2. 定义学校信息

abstract final class ExampleUniversityProfile {
  static const profile = UniversityProfile(
    id: 'example',
    displayName: '示例大学教务系统',
    baseUrl: 'https://jw.example.edu.cn',
    passwordSalt: '',
    loginPath: '/login',
    captchaPath: '/captcha',
    loginSubmitPath: '/login/submit',
    schedulePath: '/api/student/schedule',
    scheduleRefererPath: '/student/schedule',
    activePageMarkers: ['退出登录'],
  );
}

UniversityProfile 只保存简单参数。遇到动态签名、RSA、CAS、统一身份认证或多步登录时,应把逻辑写进 adapter 和对应 parser,不要继续向 profile 堆配置字段。

3. 实现适配器

class ExampleUniversityAdapter implements UniversityAdapter {
  const ExampleUniversityAdapter();

  @override
  UniversityProfile get profile => ExampleUniversityProfile.profile;

  @override
  String encryptPassword(String password) {
    return ExamplePasswordCodec.encrypt(password);
  }

  @override
  String? extractLoginToken(String html) {
    return ExampleLoginParser.extractToken(html);
  }

  @override
  UniversityLoginResult parseLoginResult(String html) {
    return ExampleLoginParser.parseResult(html);
  }

  @override
  bool isActiveSessionPage(String html) {
    return ExampleLoginParser.isLoggedIn(html);
  }

  @override
  bool isExpiredSessionPage(String html) {
    return ExampleLoginParser.isLoginPage(html);
  }

  @override
  UniversityScheduleImport parseSchedule(String responseBody) {
    final response = ExampleScheduleParser.parse(responseBody);
    return UniversityScheduleImport(
      courses: response.toCoursePreviews(),
      sectionTimes: response.sectionTimes,
      semester: response.semester,
    );
  }
}

UniversityScheduleImport 是学校层和通用课表层的边界:

  • courses:转换后的课程和每个上课 slot。
  • sectionTimes:该学校实际节次表,可来自接口或学校默认配置。
  • semester:能够可靠解析时返回学期开始日期和总周数,否则为 null。

不规则周次应写入 CourseTimeSlot.classWeek,格式为从第 1 周开始的 0/1 位图,例如 101001 表示第 1、3、6 周上课。通用查询层会优先按该位图过滤。

4. 启用适配器

当前默认适配器在 AuthApi 构造函数中选择。开发其他学校版本时改为:

AuthApi(adapter: const ExampleUniversityAdapter())

也可以在 authRepositoryProvider 中根据构建配置选择 adapter。学校数量增加后,再增加 registry 或设置页选择;无需提前把每所学校协议合并成一个大型条件分支。

5. 验证要求

至少为新学校补充以下测试:

  • 登录 token 和验证码解析。
  • 登录成功、失败、会话过期判断。
  • 密码加密或签名结果。
  • 原始课表响应解析。
  • 不规则周次、单双周和多上课地点。
  • 节次时间和学期信息转换。
  • adapter 输出的 UniversityScheduleImport。

Release 构建

Android 只构建 arm64-v8a 混淆 APK:

flutter build apk --release `
  --target-platform android-arm64 `
  --obfuscate `
  --split-debug-info=build\symbols\android-arm64 `
  --tree-shake-icons

Android 分 ABI APK:

flutter build apk --release `
  --split-per-abi `
  --obfuscate `
  --split-debug-info=build\symbols\android `
  --tree-shake-icons

Android App Bundle:

flutter build appbundle --release `
  --obfuscate `
  --split-debug-info=build\symbols\android `
  --tree-shake-icons

Windows release:

flutter build windows --release `
  --obfuscate `
  --split-debug-info=build\symbols\windows `
  --tree-shake-icons

windows 效果图

img.png

安卓 效果图

img_1.png

License

本项目为开源课表工具,仅允许个人学习、研究和非商业使用。未经作者许可,不得将本项目或衍生作品用于售卖、商业服务、广告变现或其他商业用途。

About

为四川大学专门定制的课程表查看软件,同时可以较为轻松的修改为任意学校的专用课程表

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages