fix: Standardize Error Handling in Postgres Package

[abolfazl-alemi-aa]

Summary

Updated the v1/postgres package to ensure consistent error handling across all methods. All functions now return GORM errors directly, with comprehensive documentation and test coverage demonstrating recommended patterns.

Changes

Documentation Updates

• Updated package-level error handling documentation in doc.go
• Updated method comments in 6 files to specify "GORM error" return type

Test Enhancements

• Added comprehensive error handling test suite with 4 test patterns:
  • Direct GORM error checking
  • Helper function pattern (recommended)
  • Error translation (optional)
  • Constraint violation handling

Key Improvements

• ✅ Consistency: All methods (direct and QueryBuilder) return GORM errors
• ✅ Clarity: Every method documents its error return type
• ✅ Best Practices: Three recommended patterns documented with examples
• ✅ Test Coverage: Executable examples validate all patterns

Recommended Error Handling

Pattern 1: Direct GORM Errors

err := db.First(ctx, &user, conditions)
if errors.Is(err, gorm.ErrRecordNotFound) {
    // Handle not found
}

Pattern 2: Helper Functions

func isRecordNotFound(err error) bool {
    return errors.Is(err, gorm.ErrRecordNotFound)
}

if isRecordNotFound(err) {
    // Handle consistently
}

Pattern 3: Translation (When Needed)

err = db.TranslateError(err)
if errors.Is(err, postgres.ErrRecordNotFound) {
    // Use standardized error
}