refactor(database): enhance database migration system

- Migrate from version-based to PR date-based identification
- Update collection name to 'pr_migrations_history'
- Modify migration sorting and checking mechanism
- Enhance logging and recording of migration details

Author: fulleni

lib/src/services/database_migration_service.dart

@@ -10,7 +10,7 @@ import 'package:mongo_dart/mongo_dart.dart';
 /// `migrations_history` collection to ensure idempotency and prevent
 /// redundant execution.
 ///
-/// Migrations are identified by a unique version string (YYYYMMDDHHMMSS)
+/// Migrations are identified by their PR merge date (YYYYMMDDHHMMSS)
 /// and are always applied in chronological order.
 /// {@endtemplate}
 class DatabaseMigrationService {
@@ -28,45 +28,47 @@ class DatabaseMigrationService {
   final List<Migration> _migrations;
 
   /// The name of the MongoDB collection used to track applied migrations.
-  static const String _migrationsCollectionName = 'migrations_history';
+  /// This collection stores metadata about applied Pull Request migrations.
+  static const String _migrationsCollectionName = 'pr_migrations_history';
 
   /// Initializes the migration service and applies any pending migrations.
   ///
   /// This method performs the following steps:
-  /// 1. Ensures the `migrations_history` collection exists and has a unique
-  ///    index on the `version` field.
-  /// 2. Fetches all previously applied migration versions from the database.
-  /// 3. Sorts the registered migrations by their version string.
+  /// 1. Ensures the `pr_migrations_history` collection exists and has a unique
+  ///    index on the `prDate` field.
+  /// 2. Fetches all previously applied migration PR dates from the database.
+  /// 3. Sorts the registered migrations by their `prDate` string.
   /// 4. Iterates through the sorted migrations, applying only those that
   ///    have not yet been applied.
-  /// 5. Records each successfully applied migration in the `migrations_history`
-  ///    collection.
+  /// 5. Records each successfully applied migration's `prDate` and `prId`
+  ///    in the `pr_migrations_history` collection.
   Future<void> init() async {
     _log.info('Starting database migration process...');
 
     await _ensureMigrationsCollectionAndIndex();
 
-    final appliedVersions = await _getAppliedMigrationVersions();
-    _log.fine('Applied migration versions: $appliedVersions');
+    final appliedPrDates = await _getAppliedMigrationPrDates();
+    _log.fine('Applied migration PR dates: $appliedPrDates');
 
-    // Sort migrations by version to ensure chronological application.
-    _migrations.sort((a, b) => a.version.compareTo(b.version));
+    // Sort migrations by prDate to ensure chronological application.
+    _migrations.sort((a, b) => a.prDate.compareTo(b.prDate));
 
     for (final migration in _migrations) {
-      if (!appliedVersions.contains(migration.version)) {
+      if (!appliedPrDates.contains(migration.prDate)) {
         _log.info(
-          'Applying migration V${migration.version}: ${migration.description}',
+          'Applying migration PR#${migration.prId} (Date: ${migration.prDate}): '
+          '${migration.prSummary}',
         );
         try {
           await migration.up(_db, _log);
-          await _recordMigration(migration.version);
+          await _recordMigration(migration.prDate, migration.prId);
           _log.info(
-            'Successfully applied migration V${migration.version}.',
+            'Successfully applied migration PR#${migration.prId} (Date: ${migration.prDate}).',
           );
         } catch (e, s) {
           _log.severe(
-            'Failed to apply migration V${migration.version}: '
-            '${migration.description}',
+            'Failed to apply migration PR#${migration.prId} (Date: ${migration.prDate}): '
+            '${migration.prSummary}',
             e,
             s,
           );
@@ -75,43 +77,44 @@ class DatabaseMigrationService {
         }
       } else {
         _log.fine(
-          'Migration V${migration.version} already applied. Skipping.',
+          'Migration PR#${migration.prId} (Date: ${migration.prDate}) already applied. Skipping.',
         );
       }
     }
 
     _log.info('Database migration process completed.');
   }
 
-  /// Ensures the `migrations_history` collection exists and has a unique index
-  /// on the `version` field.
+  /// Ensures the `pr_migrations_history` collection exists and has a unique index
+  /// on the `prDate` field.
   Future<void> _ensureMigrationsCollectionAndIndex() async {
-    _log.fine('Ensuring migrations_history collection and index...');
+    _log.fine('Ensuring pr_migrations_history collection and index...');
     final collection = _db.collection(_migrationsCollectionName);
     await collection.createIndex(
-      key: 'version',
+      key: 'prDate',
       unique: true,
-      name: 'version_unique_index',
+      name: 'prDate_unique_index',
     );
-    _log.fine('Migrations_history collection and index ensured.');
+    _log.fine('Pr_migrations_history collection and index ensured.');
   }
 
-  /// Retrieves a set of versions of all migrations that have already been
+  /// Retrieves a set of PR dates of all migrations that have already been
   /// applied to the database.
-  Future<Set<String>> _getAppliedMigrationVersions() async {
+  Future<Set<String>> _getAppliedMigrationPrDates() async {
     final collection = _db.collection(_migrationsCollectionName);
     final documents = await collection.find().toList();
     return documents
-        .map((doc) => doc['version'] as String)
+        .map((doc) => doc['prDate'] as String)
         .toSet();
   }
 
-  /// Records a successfully applied migration in the `migrations_history`
+  /// Records a successfully applied migration in the `pr_migrations_history`
   /// collection.
-  Future<void> _recordMigration(String version) async {
+  Future<void> _recordMigration(String prDate, String prId) async {
     final collection = _db.collection(_migrationsCollectionName);
     await collection.insertOne({
-      'version': version,
+      'prDate': prDate,
+      'prId': prId,
       'appliedAt': DateTime.now().toUtc(),
     });
   }