Improve documentation and add more tests

internal/repository/migration.go

@@ -16,11 +16,29 @@ import (
 	"github.com/golang-migrate/migrate/v4/source/iofs"
 )
 
+// Version is the current database schema version required by this version of cc-backend.
+// When the database schema changes, this version is incremented and a new migration file
+// is added to internal/repository/migrations/sqlite3/.
+//
+// Version history:
+//   - Version 10: Current version
+//
+// Migration files are embedded at build time from the migrations directory.
 const Version uint = 10
 
 //go:embed migrations/*
 var migrationFiles embed.FS
 
+// checkDBVersion verifies that the database schema version matches the expected version.
+// This is called automatically during Connect() to ensure schema compatibility.
+//
+// Returns an error if:
+//   - Database version is older than expected (needs migration)
+//   - Database version is newer than expected (needs app upgrade)
+//   - Database is in a dirty state (failed migration)
+//
+// A "dirty" database indicates a migration was started but not completed successfully.
+// This requires manual intervention to fix the database and force the version.
 func checkDBVersion(db *sql.DB) error {
 	driver, err := sqlite3.WithInstance(db, &sqlite3.Config{})
 	if err != nil {
@@ -58,6 +76,8 @@ func checkDBVersion(db *sql.DB) error {
 	return nil
 }
 
+// getMigrateInstance creates a new migration instance for the given database file.
+// This is used internally by MigrateDB, RevertDB, and ForceDB.
 func getMigrateInstance(db string) (m *migrate.Migrate, err error) {
 	d, err := iofs.New(migrationFiles, "migrations/sqlite3")
 	if err != nil {
@@ -72,6 +92,23 @@ func getMigrateInstance(db string) (m *migrate.Migrate, err error) {
 	return m, nil
 }
 
+// MigrateDB applies all pending database migrations to bring the schema up to date.
+// This should be run with the -migrate-db flag before starting the application
+// after upgrading to a new version that requires schema changes.
+//
+// Process:
+//  1. Checks current database version
+//  2. Applies all migrations from current version to target Version
+//  3. Updates schema_migrations table to track applied migrations
+//
+// Important:
+//   - Always backup your database before running migrations
+//   - Migrations are irreversible without manual intervention
+//   - If a migration fails, the database is marked "dirty" and requires manual fix
+//
+// Usage:
+//
+//	cc-backend -migrate-db
 func MigrateDB(db string) error {
 	m, err := getMigrateInstance(db)
 	if err != nil {
@@ -107,6 +144,17 @@ func MigrateDB(db string) error {
 	return nil
 }
 
+// RevertDB rolls back the database schema to the previous version (Version - 1).
+// This is primarily used for testing or emergency rollback scenarios.
+//
+// Warning:
+//   - This may cause data loss if newer schema added columns/tables
+//   - Always backup before reverting
+//   - Not all migrations are safely reversible
+//
+// Usage:
+//
+//	cc-backend -revert-db
 func RevertDB(db string) error {
 	m, err := getMigrateInstance(db)
 	if err != nil {
@@ -125,6 +173,21 @@ func RevertDB(db string) error {
 	return nil
 }
 
+// ForceDB forces the database schema version to the current Version without running migrations.
+// This is only used to recover from failed migrations that left the database in a "dirty" state.
+//
+// When to use:
+//   - After manually fixing a failed migration
+//   - When you've manually applied schema changes and need to update the version marker
+//
+// Warning:
+//   - This does NOT apply any schema changes
+//   - Only use after manually verifying the schema is correct
+//   - Improper use can cause schema/version mismatch
+//
+// Usage:
+//
+//	cc-backend -force-db
 func ForceDB(db string) error {
 	m, err := getMigrateInstance(db)
 	if err != nil {