refactor: decouple schedule data source contracts

Author: jjoonleo

CONTEXT.md

@@ -5,6 +5,26 @@ release, and feature discussions use the same terms.
 
 ## Language
 
+**OnTime User**:
+A person's OnTime account profile that owns schedules, places, preparation defaults, and notification preferences.
+_Avoid_: User identity, analytics subject, device
+
+**Schedule**:
+A planned commitment with an intended time, destination place, travel time, and optional preparation plan.
+_Avoid_: Alarm, notification, calendar row
+
+**Place**:
+The destination or location label attached to a Schedule.
+_Avoid_: Route, address record, notification location
+
+**Preparation**:
+An ordered plan of steps the user intends to complete before leaving for a Schedule.
+_Avoid_: Reminder, notification, alarm
+
+**Preparation Step**:
+One named action in a Preparation with an expected duration.
+_Avoid_: UI row, checklist widget, notification step
+
 **Product Usage Event**:
 A named record that a user performed a product-relevant action, excluding raw personal content.
 _Avoid_: User activity, tracking event, raw interaction log
@@ -107,6 +127,12 @@ _Avoid_: Notification, native alarm
 
 ## Relationships
 
+- An **OnTime User** may own zero or more **Schedules**.
+- A **Schedule** has one **Place**.
+- A **Schedule** may use one **Preparation**.
+- A **Preparation** contains zero or more **Preparation Steps** in user-defined order.
+- A **Preparation Step** belongs to exactly one **Preparation**.
+- A **Schedule Notification** uses **Schedule** and **Preparation** timing, but is not itself a **Schedule** or **Preparation**.
 - A **Product Usage Event** may describe a schedule, preparation, notification, alarm, onboarding, or account action without storing the user's raw schedule names, notes, place names, credentials, tokens, or free text.
 - First-release **Product Usage Events** are **Workflow Milestone Events**, not every tap or raw navigation step.
 - First-release **Workflow Milestone Events** cover analytics preference, onboarding, authentication, schedule, notification permission, alarm, and schedule-finish outcomes.
@@ -155,8 +181,14 @@ _Avoid_: Notification, native alarm
 > **Dev:** "Should the analytics event include the schedule note so we can understand why users are late?"
 > **Domain expert:** "No. A **Product Usage Event** can say a schedule was finished late, but it must not include the user's raw note."
 
+> **Dev:** "Can a **Schedule Notification** replace the **Schedule** if the user taps it?"
+> **Domain expert:** "No. The **Schedule Notification** only prompts preparation for the **Schedule**; the **Schedule** remains the planned commitment."
+
 ## Flagged ambiguities
 
+- "User" was overloaded as both the human actor and stored profile; resolved: use **OnTime User** for the account/profile concept and plain user only for the person performing an action.
+- "Schedule" was used near notification and alarm flows; resolved: a **Schedule** is the planned commitment, while notifications and alarms are delivery experiences for preparation timing.
+- "Preparation state" was ambiguous between step progress and display styling; resolved: **Preparation Step** progress belongs to preparation language, while visual labels should not redefine the domain.
 - "User activities" was used broadly; resolved: the canonical term is **Product Usage Event**, and raw personal content is out of scope.
 - "Analytics" was used to include all possible purposes; resolved: marketing and personalization are deferred, not first-release purposes.
 - "User identity" for analytics was ambiguous; resolved: analytics uses a **Pseudonymous Analytics Subject**, not directly identifying user data.

lib/data/data_sources/schedule_local_data_source.dart

@@ -1,21 +1,20 @@
 import 'package:injectable/injectable.dart';
 import 'package:on_time_front/core/database/database.dart';
-import 'package:on_time_front/data/mappers/domain_persistence_mappers.dart';
-import 'package:on_time_front/domain/entities/schedule_entity.dart';
+import 'package:on_time_front/data/tables/schedule_with_place_model.dart';
 
 abstract interface class ScheduleLocalDataSource {
-  Future<void> createSchedule(ScheduleEntity scheduleEntity);
+  Future<void> createSchedule(ScheduleWithPlace schedule);
 
-  Future<List<ScheduleEntity>> getSchedulesByDate(
+  Future<List<ScheduleWithPlace>> getSchedulesByDate(
     DateTime startDate,
     DateTime? endDate,
   );
 
-  Future<ScheduleEntity> getScheduleById(String id);
+  Future<ScheduleWithPlace> getScheduleById(String id);
 
-  Future<void> updateSchedule(ScheduleEntity scheduleEntity);
+  Future<void> updateSchedule(Schedule schedule);
 
-  Future<void> deleteSchedule(ScheduleEntity scheduleEntity);
+  Future<void> deleteSchedule(Schedule schedule);
 }
 
 @Injectable(as: ScheduleLocalDataSource)
@@ -25,38 +24,30 @@ class ScheduleLocalDataSourceImpl implements ScheduleLocalDataSource {
   ScheduleLocalDataSourceImpl({required this.appDatabase});
 
   @override
-  Future<void> createSchedule(ScheduleEntity scheduleEntity) async {
-    await appDatabase.scheduleDao.createSchedule(
-      scheduleEntity.toScheduleWithPlaceRow(),
-    );
+  Future<void> createSchedule(ScheduleWithPlace schedule) async {
+    await appDatabase.scheduleDao.createSchedule(schedule);
   }
 
   @override
-  Future<void> deleteSchedule(ScheduleEntity schedulEntity) async {
-    await appDatabase.scheduleDao.deleteSchedule(schedulEntity.toScheduleRow());
+  Future<void> deleteSchedule(Schedule schedule) async {
+    await appDatabase.scheduleDao.deleteSchedule(schedule);
   }
 
   @override
-  Future<ScheduleEntity> getScheduleById(String id) async {
-    final scheduleWithPlaceModel = await appDatabase.scheduleDao
-        .getScheduleById(id);
-    return scheduleWithPlaceModel.toScheduleEntity();
+  Future<ScheduleWithPlace> getScheduleById(String id) async {
+    return appDatabase.scheduleDao.getScheduleById(id);
   }
 
   @override
-  Future<List<ScheduleEntity>> getSchedulesByDate(
+  Future<List<ScheduleWithPlace>> getSchedulesByDate(
     DateTime startDate,
     DateTime? endDate,
   ) async {
-    final scheduleWithPlaceModel = await appDatabase.scheduleDao
-        .getSchedulesByDate(startDate, endDate);
-    return scheduleWithPlaceModel.map((e) => e.toScheduleEntity()).toList();
+    return appDatabase.scheduleDao.getSchedulesByDate(startDate, endDate);
   }
 
   @override
-  Future<void> updateSchedule(ScheduleEntity scheduleEntity) async {
-    await appDatabase.scheduleDao.updateSchedule(
-      scheduleEntity.toScheduleRow(),
-    );
+  Future<void> updateSchedule(Schedule schedule) async {
+    await appDatabase.scheduleDao.updateSchedule(schedule);
   }
 }

lib/data/data_sources/schedule_remote_data_source.dart

@@ -6,24 +6,19 @@ import 'package:on_time_front/data/models/create_schedule_request_model.dart';
 import 'package:on_time_front/data/models/get_schedule_response_model.dart';
 import 'package:on_time_front/data/models/update_schedule_request_model.dart';
 
-import 'package:on_time_front/domain/entities/schedule_entity.dart';
-
 abstract interface class ScheduleRemoteDataSource {
-  Future<void> createSchedule(ScheduleEntity schedule);
+  Future<void> createSchedule(CreateScheduleRequestModel schedule);
 
-  Future<List<ScheduleEntity>> getSchedulesByDate(
+  Future<List<GetScheduleResponseModel>> getSchedulesByDate(
     DateTime startDate,
     DateTime? endDate,
   );
 
-  Future<ScheduleEntity> getScheduleById(String id);
+  Future<GetScheduleResponseModel> getScheduleById(String id);
 
-  Future<void> updateSchedule(
-    ScheduleEntity schedule, {
-    bool includePreparationSource = false,
-  });
+  Future<void> updateSchedule(UpdateScheduleRequestModel schedule);
 
-  Future<void> deleteSchedule(ScheduleEntity schedule);
+  Future<void> deleteSchedule(String scheduleId);
 
   Future<void> startSchedule(String scheduleId);
 
@@ -36,13 +31,11 @@ class ScheduleRemoteDataSourceImpl implements ScheduleRemoteDataSource {
   ScheduleRemoteDataSourceImpl(this.dio);
 
   @override
-  Future<void> createSchedule(ScheduleEntity schedule) async {
+  Future<void> createSchedule(CreateScheduleRequestModel schedule) async {
     try {
-      CreateScheduleRequestModel createScheduleModel =
-          CreateScheduleRequestModel.fromEntity(schedule);
       final result = await dio.post(
         Endpoint.createSchedule,
-        data: createScheduleModel.toJson(),
+        data: schedule.toJson(),
       );
       if (result.statusCode == 200) {
         return;
@@ -55,19 +48,11 @@ class ScheduleRemoteDataSourceImpl implements ScheduleRemoteDataSource {
   }
 
   @override
-  Future<void> updateSchedule(
-    ScheduleEntity schedule, {
-    bool includePreparationSource = false,
-  }) async {
+  Future<void> updateSchedule(UpdateScheduleRequestModel schedule) async {
     try {
-      UpdateScheduleRequestModel updateScheduleModel =
-          UpdateScheduleRequestModel.fromEntity(
-            schedule,
-            includePreparationSource: includePreparationSource,
-          );
       final result = await dio.put(
-        Endpoint.updateSchedule(schedule.id),
-        data: updateScheduleModel.toJson(),
+        Endpoint.updateSchedule(schedule.scheduleId),
+        data: schedule.toJson(),
       );
       if (result.statusCode == 200) {
         return;
@@ -80,9 +65,9 @@ class ScheduleRemoteDataSourceImpl implements ScheduleRemoteDataSource {
   }
 
   @override
-  Future<void> deleteSchedule(ScheduleEntity schedule) async {
+  Future<void> deleteSchedule(String scheduleId) async {
     try {
-      final result = await dio.delete(Endpoint.deleteScheduleById(schedule.id));
+      final result = await dio.delete(Endpoint.deleteScheduleById(scheduleId));
       if (result.statusCode == 200) {
         return;
       } else {
@@ -125,13 +110,13 @@ class ScheduleRemoteDataSourceImpl implements ScheduleRemoteDataSource {
   }
 
   @override
-  Future<ScheduleEntity> getScheduleById(String id) async {
+  Future<GetScheduleResponseModel> getScheduleById(String id) async {
     try {
       final result = await dio.get(Endpoint.getScheduleById(id));
       if (result.statusCode == 200) {
         final GetScheduleResponseModel schedule =
             GetScheduleResponseModel.fromJson(result.data["data"]);
-        return schedule.toEntity();
+        return schedule;
       } else {
         throw Exception('Error getting schedules');
       }
@@ -141,7 +126,7 @@ class ScheduleRemoteDataSourceImpl implements ScheduleRemoteDataSource {
   }
 
   @override
-  Future<List<ScheduleEntity>> getSchedulesByDate(
+  Future<List<GetScheduleResponseModel>> getSchedulesByDate(
     DateTime startDate,
     DateTime? endDate,
   ) async {
@@ -154,9 +139,9 @@ class ScheduleRemoteDataSourceImpl implements ScheduleRemoteDataSource {
         },
       );
       if (result.statusCode == 200) {
-        final List<ScheduleEntity> schedules = result.data["data"]
-            .map<ScheduleEntity>(
-              (e) => GetScheduleResponseModel.fromJson(e).toEntity(),
+        final List<GetScheduleResponseModel> schedules = result.data["data"]
+            .map<GetScheduleResponseModel>(
+              (e) => GetScheduleResponseModel.fromJson(e),
             )
             .toList();
         return schedules;

lib/data/repositories/schedule_repository_impl.dart

@@ -4,6 +4,8 @@ import 'package:collection/collection.dart';
 import 'package:injectable/injectable.dart';
 import 'package:on_time_front/data/data_sources/schedule_local_data_source.dart';
 import 'package:on_time_front/data/data_sources/schedule_remote_data_source.dart';
+import 'package:on_time_front/data/models/create_schedule_request_model.dart';
+import 'package:on_time_front/data/models/update_schedule_request_model.dart';
 import 'package:on_time_front/domain/entities/schedule_entity.dart';
 import 'package:on_time_front/domain/repositories/schedule_repository.dart';
 import 'package:on_time_front/domain/repositories/timed_preparation_repository.dart';
@@ -50,7 +52,9 @@ class ScheduleRepositoryImpl implements ScheduleRepository {
   @override
   Future<void> createSchedule(ScheduleEntity schedule) async {
     try {
-      await scheduleRemoteDataSource.createSchedule(schedule);
+      await scheduleRemoteDataSource.createSchedule(
+        CreateScheduleRequestModel.fromEntity(schedule),
+      );
       //await scheduleLocalDataSource.createSchedule(schedule);
       _emitUpsertedSchedule(schedule);
     } catch (e) {
@@ -61,7 +65,7 @@ class ScheduleRepositoryImpl implements ScheduleRepository {
   @override
   Future<void> deleteSchedule(ScheduleEntity schedule) async {
     try {
-      await scheduleRemoteDataSource.deleteSchedule(schedule);
+      await scheduleRemoteDataSource.deleteSchedule(schedule.id);
       await _clearTimedPreparationSafe(schedule.id);
       //await scheduleLocalDataSource.deleteSchedule(schedule);
       _emitScheduleSet(
@@ -86,7 +90,9 @@ class ScheduleRepositoryImpl implements ScheduleRepository {
   @override
   Future<ScheduleEntity> getScheduleById(String id) async {
     try {
-      final schedule = await scheduleRemoteDataSource.getScheduleById(id);
+      final schedule = (await scheduleRemoteDataSource.getScheduleById(
+        id,
+      )).toEntity();
       if (_isEnded(schedule.doneStatus)) {
         await _clearTimedPreparationSafe(schedule.id);
       }
@@ -103,10 +109,10 @@ class ScheduleRepositoryImpl implements ScheduleRepository {
     DateTime? endDate,
   ) async {
     try {
-      final schedules = await scheduleRemoteDataSource.getSchedulesByDate(
+      final schedules = (await scheduleRemoteDataSource.getSchedulesByDate(
         startDate,
         endDate,
-      );
+      )).map((schedule) => schedule.toEntity()).toList();
       for (final schedule in schedules) {
         if (_isEnded(schedule.doneStatus)) {
           await _clearTimedPreparationSafe(schedule.id);
@@ -130,13 +136,15 @@ class ScheduleRepositoryImpl implements ScheduleRepository {
   }) async {
     try {
       await scheduleRemoteDataSource.updateSchedule(
-        schedule,
-        includePreparationSource: includePreparationSource,
+        UpdateScheduleRequestModel.fromEntity(
+          schedule,
+          includePreparationSource: includePreparationSource,
+        ),
       );
       await _clearTimedPreparationSafe(schedule.id);
-      final refreshedSchedule = await scheduleRemoteDataSource.getScheduleById(
+      final refreshedSchedule = (await scheduleRemoteDataSource.getScheduleById(
         schedule.id,
-      );
+      )).toEntity();
       if (_isEnded(refreshedSchedule.doneStatus)) {
         await _clearTimedPreparationSafe(refreshedSchedule.id);
       }

test/data/data_sources/schedule_data_source_contract_test.dart

@@ -0,0 +1,37 @@
+import 'dart:io';
+
+import 'package:flutter_test/flutter_test.dart';
+
+void main() {
+  test(
+    'schedule remote data source contract does not expose domain entities',
+    () {
+      final violations = _scheduleEntityViolations(
+        'lib/data/data_sources/schedule_remote_data_source.dart',
+      );
+
+      expect(violations, isEmpty);
+    },
+  );
+
+  test(
+    'schedule local data source contract does not expose domain entities',
+    () {
+      final violations = _scheduleEntityViolations(
+        'lib/data/data_sources/schedule_local_data_source.dart',
+      );
+
+      expect(violations, isEmpty);
+    },
+  );
+}
+
+List<String> _scheduleEntityViolations(String path) {
+  final lines = File(path).readAsLinesSync();
+  return [
+    for (var index = 0; index < lines.length; index++)
+      if (lines[index].contains('domain/entities/schedule_entity.dart') ||
+          lines[index].contains('ScheduleEntity'))
+        '$path:${index + 1}: ${lines[index].trim()}',
+  ];
+}