feat: add validated semester and lesson calculations

mobile/lib/domain/app_settings.dart

@@ -0,0 +1,37 @@
+import 'semester.dart';
+
+enum ColorMode { single, multicolor }
+
+class AppSettings {
+  const AppSettings({
+    this.semester,
+    this.remindersEnabled = true,
+    this.reminderMinutes = 15,
+    this.colorMode = ColorMode.multicolor,
+    this.singleColorArgb = 0xFF348F91,
+    this.calendarEnabled = false,
+    this.calendarId,
+  });
+  final Semester? semester;
+  final bool remindersEnabled, calendarEnabled;
+  final int reminderMinutes, singleColorArgb;
+  final ColorMode colorMode;
+  final String? calendarId;
+  AppSettings copyWith({
+    Semester? semester,
+    bool? remindersEnabled,
+    int? reminderMinutes,
+    ColorMode? colorMode,
+    int? singleColorArgb,
+    bool? calendarEnabled,
+    String? calendarId,
+  }) => AppSettings(
+    semester: semester ?? this.semester,
+    remindersEnabled: remindersEnabled ?? this.remindersEnabled,
+    reminderMinutes: reminderMinutes ?? this.reminderMinutes,
+    colorMode: colorMode ?? this.colorMode,
+    singleColorArgb: singleColorArgb ?? this.singleColorArgb,
+    calendarEnabled: calendarEnabled ?? this.calendarEnabled,
+    calendarId: calendarId ?? this.calendarId,
+  );
+}

mobile/lib/domain/course.dart

@@ -0,0 +1,30 @@
+enum CourseSource { school, file, demo }
+
+class Course {
+  Course({
+    required this.id,
+    required this.name,
+    required this.teacher,
+    required this.room,
+    required this.weekday,
+    required this.startPeriod,
+    required this.endPeriod,
+    required Set<int> weeks,
+    required this.source,
+  }) : weeks = Set.unmodifiable(weeks) {
+    if ([id, name, teacher, room].any((value) => value.trim().isEmpty) ||
+        weekday < 1 ||
+        weekday > 7 ||
+        startPeriod < 1 ||
+        endPeriod > 11 ||
+        endPeriod < startPeriod ||
+        weeks.isEmpty ||
+        weeks.any((week) => week < 1 || week > 30)) {
+      throw ArgumentError('课程字段、节次或周次无效');
+    }
+  }
+  final String id, name, teacher, room;
+  final int weekday, startPeriod, endPeriod;
+  final Set<int> weeks;
+  final CourseSource source;
+}

mobile/lib/domain/course_occurrence.dart

@@ -0,0 +1,17 @@
+import 'package:timezone/timezone.dart' as tz;
+
+import 'course.dart';
+
+class CourseOccurrence {
+  const CourseOccurrence({
+    required this.key,
+    required this.course,
+    required this.week,
+    required this.start,
+    required this.end,
+  });
+  final String key;
+  final Course course;
+  final int week;
+  final tz.TZDateTime start, end;
+}

mobile/lib/domain/lesson_times.dart

@@ -0,0 +1,20 @@
+class LessonSlot {
+  const LessonSlot(this.period, this.startMinute, this.endMinute);
+  final int period, startMinute, endMinute;
+}
+
+const lessonSlots = [
+  LessonSlot(1, 510, 555),
+  LessonSlot(2, 560, 605),
+  LessonSlot(3, 620, 665),
+  LessonSlot(4, 670, 715),
+  LessonSlot(5, 870, 915),
+  LessonSlot(6, 920, 965),
+  LessonSlot(7, 980, 1025),
+  LessonSlot(8, 1030, 1075),
+  LessonSlot(9, 1170, 1215),
+  LessonSlot(10, 1220, 1265),
+  LessonSlot(11, 1270, 1315),
+];
+String minuteLabel(int minute) =>
+    '${(minute ~/ 60).toString().padLeft(2, '0')}:${(minute % 60).toString().padLeft(2, '0')}';

mobile/lib/domain/schedule_engine.dart

@@ -0,0 +1,79 @@
+import 'course.dart';
+import 'semester.dart';
+import 'course_occurrence.dart';
+import 'lesson_times.dart';
+
+import 'package:timezone/timezone.dart' as tz;
+
+export 'course.dart';
+export 'semester.dart';
+export 'lesson_times.dart';
+export 'course_occurrence.dart';
+
+class ScheduleEngine {
+  static DateTime schoolDate(DateTime instant) {
+    final local = tz.TZDateTime.from(instant, tz.getLocation('Asia/Shanghai'));
+    return DateTime.utc(local.year, local.month, local.day);
+  }
+
+  static int? weekNumber(Semester semester, DateTime schoolDate) {
+    final date = DateTime.utc(
+      schoolDate.year,
+      schoolDate.month,
+      schoolDate.day,
+    );
+    final delta = date.difference(semester.firstMonday).inDays;
+    if (delta < 0 || delta >= semester.totalWeeks * 7) return null;
+    return delta ~/ 7 + 1;
+  }
+
+  static List<CourseOccurrence> occurrences(
+    List<Course> courses,
+    Semester semester,
+  ) {
+    final result = <CourseOccurrence>[];
+    final zone = tz.getLocation('Asia/Shanghai');
+    for (final course in courses) {
+      for (final week in course.weeks) {
+        if (week > semester.totalWeeks) continue;
+        final day = semester.firstMonday.add(
+          Duration(days: (week - 1) * 7 + course.weekday - 1),
+        );
+        if (day.isBefore(semester.startDate)) continue;
+        final first = lessonSlots[course.startPeriod - 1].startMinute;
+        final last = lessonSlots[course.endPeriod - 1].endMinute;
+        result.add(
+          CourseOccurrence(
+            key: '${course.id}/${day.toIso8601String().substring(0, 10)}',
+            course: course,
+            week: week,
+            start: tz.TZDateTime(
+              zone,
+              day.year,
+              day.month,
+              day.day,
+              first ~/ 60,
+              first % 60,
+            ),
+            end: tz.TZDateTime(
+              zone,
+              day.year,
+              day.month,
+              day.day,
+              last ~/ 60,
+              last % 60,
+            ),
+          ),
+        );
+      }
+    }
+    result.sort((a, b) {
+      final order = a.start.compareTo(b.start);
+      return order == 0 ? a.key.compareTo(b.key) : order;
+    });
+    return result;
+  }
+
+  static bool overlaps(CourseOccurrence a, CourseOccurrence b) =>
+      a.start.isBefore(b.end) && b.start.isBefore(a.end);
+}

mobile/lib/domain/semester.dart

@@ -0,0 +1,12 @@
+class Semester {
+  Semester({required DateTime startDate, required this.totalWeeks})
+    : startDate = DateTime.utc(startDate.year, startDate.month, startDate.day) {
+    if (totalWeeks < 1 || totalWeeks > 30) {
+      throw ArgumentError('学期周数应为 1–30');
+    }
+  }
+  DateTime get firstMonday =>
+      startDate.subtract(Duration(days: startDate.weekday - 1));
+  final DateTime startDate;
+  final int totalWeeks;
+}

mobile/lib/main.dart

@@ -0,0 +1,122 @@
+import 'package:flutter/material.dart';
+
+void main() {
+  runApp(const MyApp());
+}
+
+class MyApp extends StatelessWidget {
+  const MyApp({super.key});
+
+  // This widget is the root of your application.
+  @override
+  Widget build(BuildContext context) {
+    return MaterialApp(
+      title: 'Flutter Demo',
+      theme: ThemeData(
+        // This is the theme of your application.
+        //
+        // TRY THIS: Try running your application with "flutter run". You'll see
+        // the application has a purple toolbar. Then, without quitting the app,
+        // try changing the seedColor in the colorScheme below to Colors.green
+        // and then invoke "hot reload" (save your changes or press the "hot
+        // reload" button in a Flutter-supported IDE, or press "r" if you used
+        // the command line to start the app).
+        //
+        // Notice that the counter didn't reset back to zero; the application
+        // state is not lost during the reload. To reset the state, use hot
+        // restart instead.
+        //
+        // This works for code too, not just values: Most code changes can be
+        // tested with just a hot reload.
+        colorScheme: .fromSeed(seedColor: Colors.deepPurple),
+      ),
+      home: const MyHomePage(title: 'Flutter Demo Home Page'),
+    );
+  }
+}
+
+class MyHomePage extends StatefulWidget {
+  const MyHomePage({super.key, required this.title});
+
+  // This widget is the home page of your application. It is stateful, meaning
+  // that it has a State object (defined below) that contains fields that affect
+  // how it looks.
+
+  // This class is the configuration for the state. It holds the values (in this
+  // case the title) provided by the parent (in this case the App widget) and
+  // used by the build method of the State. Fields in a Widget subclass are
+  // always marked "final".
+
+  final String title;
+
+  @override
+  State<MyHomePage> createState() => _MyHomePageState();
+}
+
+class _MyHomePageState extends State<MyHomePage> {
+  int _counter = 0;
+
+  void _incrementCounter() {
+    setState(() {
+      // This call to setState tells the Flutter framework that something has
+      // changed in this State, which causes it to rerun the build method below
+      // so that the display can reflect the updated values. If we changed
+      // _counter without calling setState(), then the build method would not be
+      // called again, and so nothing would appear to happen.
+      _counter++;
+    });
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    // This method is rerun every time setState is called, for instance as done
+    // by the _incrementCounter method above.
+    //
+    // The Flutter framework has been optimized to make rerunning build methods
+    // fast, so that you can just rebuild anything that needs updating rather
+    // than having to individually change instances of widgets.
+    return Scaffold(
+      appBar: AppBar(
+        // TRY THIS: Try changing the color here to a specific color (to
+        // Colors.amber, perhaps?) and trigger a hot reload to see the AppBar
+        // change color while the other colors stay the same.
+        backgroundColor: Theme.of(context).colorScheme.inversePrimary,
+        // Here we take the value from the MyHomePage object that was created by
+        // the App.build method, and use it to set our appbar title.
+        title: Text(widget.title),
+      ),
+      body: Center(
+        // Center is a layout widget. It takes a single child and positions it
+        // in the middle of the parent.
+        child: Column(
+          // Column is also a layout widget. It takes a list of children and
+          // arranges them vertically. By default, it sizes itself to fit its
+          // children horizontally, and tries to be as tall as its parent.
+          //
+          // Column has various properties to control how it sizes itself and
+          // how it positions its children. Here we use mainAxisAlignment to
+          // center the children vertically; the main axis here is the vertical
+          // axis because Columns are vertical (the cross axis would be
+          // horizontal).
+          //
+          // TRY THIS: Invoke "debug painting" (choose the "Toggle Debug Paint"
+          // action in the IDE, or press "p" in the console), to see the
+          // wireframe for each widget.
+          mainAxisAlignment: .center,
+          children: [
+            const Text('You have pushed the button this many times:'),
+            Text(
+              '$_counter',
+              style: Theme.of(context).textTheme.headlineMedium,
+            ),
+          ],
+        ),
+      ),
+      floatingActionButton: FloatingActionButton(
+        onPressed: _incrementCounter,
+        tooltip: 'Increment',
+        child: const Icon(Icons.add),
+      ),
+    );
+  }
+}