Migrate from Gin to Echo framework and add comprehensive integration tests

Major changes:
- Migrate all handlers from Gin to Echo framework
- Add new apperrors, echohelpers, and validator packages
- Update middleware for Echo compatibility
- Add ArchivedHandler to task categorization chain (archived tasks go to cancelled_tasks column)
- Add 6 new integration tests:
  - RecurringTaskLifecycle: NextDueDate advancement for weekly/monthly tasks
  - MultiUserSharing: Complex sharing with user removal
  - TaskStateTransitions: All state transitions and kanban column changes
  - DateBoundaryEdgeCases: Threshold boundary testing
  - CascadeOperations: Residence deletion cascade effects
  - MultiUserOperations: Shared residence collaboration
- Add single-purpose repository functions for kanban columns (GetOverdueTasks, GetDueSoonTasks, etc.)
- Fix RemoveUser route param mismatch (userId -> user_id)
- Fix determineExpectedColumn helper to correctly prioritize in_progress over overdue

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

internal/handlers/residence_handler.go

@@ -1,17 +1,18 @@
 package handlers
 
 import (
-	"errors"
 	"net/http"
 	"strconv"
 
-	"github.com/gin-gonic/gin"
+	"github.com/labstack/echo/v4"
 
+	"github.com/treytartt/casera-api/internal/apperrors"
 	"github.com/treytartt/casera-api/internal/dto/requests"
 	"github.com/treytartt/casera-api/internal/i18n"
 	"github.com/treytartt/casera-api/internal/middleware"
 	"github.com/treytartt/casera-api/internal/models"
 	"github.com/treytartt/casera-api/internal/services"
+	"github.com/treytartt/casera-api/internal/validator"
 )
 
 // ResidenceHandler handles residence-related HTTP requests
@@ -31,343 +32,252 @@ func NewResidenceHandler(residenceService *services.ResidenceService, pdfService
 }
 
 // ListResidences handles GET /api/residences/
-func (h *ResidenceHandler) ListResidences(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) ListResidences(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 
 	response, err := h.residenceService.ListResidences(user.ID)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, response)
+	return c.JSON(http.StatusOK, response)
 }
 
 // GetMyResidences handles GET /api/residences/my-residences/
-func (h *ResidenceHandler) GetMyResidences(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) GetMyResidences(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 	userNow := middleware.GetUserNow(c)
 
 	response, err := h.residenceService.GetMyResidences(user.ID, userNow)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, response)
+	return c.JSON(http.StatusOK, response)
 }
 
 // GetSummary handles GET /api/residences/summary/
 // Returns just the task statistics summary without full residence data
-func (h *ResidenceHandler) GetSummary(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) GetSummary(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 	userNow := middleware.GetUserNow(c)
 
 	summary, err := h.residenceService.GetSummary(user.ID, userNow)
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, summary)
+	return c.JSON(http.StatusOK, summary)
 }
 
 // GetResidence handles GET /api/residences/:id/
-func (h *ResidenceHandler) GetResidence(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) GetResidence(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 
 	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": i18n.LocalizedMessage(c, "error.invalid_residence_id")})
-		return
+		return apperrors.BadRequest("error.invalid_residence_id")
 	}
 
 	response, err := h.residenceService.GetResidence(uint(residenceID), user.ID)
 	if err != nil {
-		switch {
-		case errors.Is(err, services.ErrResidenceNotFound):
-			c.JSON(http.StatusNotFound, gin.H{"error": i18n.LocalizedMessage(c, "error.residence_not_found")})
-		case errors.Is(err, services.ErrResidenceAccessDenied):
-			c.JSON(http.StatusForbidden, gin.H{"error": i18n.LocalizedMessage(c, "error.residence_access_denied")})
-		default:
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		}
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, response)
+	return c.JSON(http.StatusOK, response)
 }
 
 // CreateResidence handles POST /api/residences/
-func (h *ResidenceHandler) CreateResidence(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) CreateResidence(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 
 	var req requests.CreateResidenceRequest
-	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
-		return
+	if err := c.Bind(&req); err != nil {
+		return apperrors.BadRequest("error.invalid_request")
+	}
+	if err := c.Validate(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, validator.FormatValidationErrors(err))
 	}
 
 	response, err := h.residenceService.CreateResidence(&req, user.ID)
 	if err != nil {
-		if errors.Is(err, services.ErrPropertiesLimitReached) {
-			c.JSON(http.StatusForbidden, gin.H{"error": i18n.LocalizedMessage(c, "error.properties_limit_reached")})
-			return
-		}
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		return
+		return err
 	}
 
-	c.JSON(http.StatusCreated, response)
+	return c.JSON(http.StatusCreated, response)
 }
 
 // UpdateResidence handles PUT/PATCH /api/residences/:id/
-func (h *ResidenceHandler) UpdateResidence(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) UpdateResidence(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 
 	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": i18n.LocalizedMessage(c, "error.invalid_residence_id")})
-		return
+		return apperrors.BadRequest("error.invalid_residence_id")
 	}
 
 	var req requests.UpdateResidenceRequest
-	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
-		return
+	if err := c.Bind(&req); err != nil {
+		return apperrors.BadRequest("error.invalid_request")
+	}
+	if err := c.Validate(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, validator.FormatValidationErrors(err))
 	}
 
 	response, err := h.residenceService.UpdateResidence(uint(residenceID), user.ID, &req)
 	if err != nil {
-		switch {
-		case errors.Is(err, services.ErrResidenceNotFound):
-			c.JSON(http.StatusNotFound, gin.H{"error": i18n.LocalizedMessage(c, "error.residence_not_found")})
-		case errors.Is(err, services.ErrNotResidenceOwner):
-			c.JSON(http.StatusForbidden, gin.H{"error": i18n.LocalizedMessage(c, "error.not_residence_owner")})
-		default:
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		}
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, response)
+	return c.JSON(http.StatusOK, response)
 }
 
 // DeleteResidence handles DELETE /api/residences/:id/
-func (h *ResidenceHandler) DeleteResidence(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) DeleteResidence(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 
 	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": i18n.LocalizedMessage(c, "error.invalid_residence_id")})
-		return
+		return apperrors.BadRequest("error.invalid_residence_id")
 	}
 
 	response, err := h.residenceService.DeleteResidence(uint(residenceID), user.ID)
 	if err != nil {
-		switch {
-		case errors.Is(err, services.ErrResidenceNotFound):
-			c.JSON(http.StatusNotFound, gin.H{"error": i18n.LocalizedMessage(c, "error.residence_not_found")})
-		case errors.Is(err, services.ErrNotResidenceOwner):
-			c.JSON(http.StatusForbidden, gin.H{"error": i18n.LocalizedMessage(c, "error.not_residence_owner")})
-		default:
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		}
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, response)
+	return c.JSON(http.StatusOK, response)
 }
 
 // GenerateShareCode handles POST /api/residences/:id/generate-share-code/
-func (h *ResidenceHandler) GenerateShareCode(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) GenerateShareCode(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 
 	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": i18n.LocalizedMessage(c, "error.invalid_residence_id")})
-		return
+		return apperrors.BadRequest("error.invalid_residence_id")
 	}
 
 	var req requests.GenerateShareCodeRequest
 	// Request body is optional
-	c.ShouldBindJSON(&req)
+	c.Bind(&req)
 
 	response, err := h.residenceService.GenerateShareCode(uint(residenceID), user.ID, req.ExpiresInHours)
 	if err != nil {
-		switch {
-		case errors.Is(err, services.ErrResidenceNotFound):
-			c.JSON(http.StatusNotFound, gin.H{"error": i18n.LocalizedMessage(c, "error.residence_not_found")})
-		case errors.Is(err, services.ErrNotResidenceOwner):
-			c.JSON(http.StatusForbidden, gin.H{"error": i18n.LocalizedMessage(c, "error.not_residence_owner")})
-		default:
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		}
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, response)
+	return c.JSON(http.StatusOK, response)
 }
 
 // GenerateSharePackage handles POST /api/residences/:id/generate-share-package/
 // Returns a share code with metadata for creating a .casera package file
-func (h *ResidenceHandler) GenerateSharePackage(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) GenerateSharePackage(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 
 	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": i18n.LocalizedMessage(c, "error.invalid_residence_id")})
-		return
+		return apperrors.BadRequest("error.invalid_residence_id")
 	}
 
 	var req requests.GenerateShareCodeRequest
 	// Request body is optional (for expires_in_hours)
-	c.ShouldBindJSON(&req)
+	c.Bind(&req)
 
 	response, err := h.residenceService.GenerateSharePackage(uint(residenceID), user.ID, req.ExpiresInHours)
 	if err != nil {
-		switch {
-		case errors.Is(err, services.ErrResidenceNotFound):
-			c.JSON(http.StatusNotFound, gin.H{"error": i18n.LocalizedMessage(c, "error.residence_not_found")})
-		case errors.Is(err, services.ErrNotResidenceOwner):
-			c.JSON(http.StatusForbidden, gin.H{"error": i18n.LocalizedMessage(c, "error.not_residence_owner")})
-		default:
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		}
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, response)
+	return c.JSON(http.StatusOK, response)
 }
 
 // JoinWithCode handles POST /api/residences/join-with-code/
-func (h *ResidenceHandler) JoinWithCode(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) JoinWithCode(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 
 	var req requests.JoinWithCodeRequest
-	if err := c.ShouldBindJSON(&req); err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
-		return
+	if err := c.Bind(&req); err != nil {
+		return apperrors.BadRequest("error.invalid_request")
 	}
 
 	response, err := h.residenceService.JoinWithCode(req.Code, user.ID)
 	if err != nil {
-		switch {
-		case errors.Is(err, services.ErrShareCodeInvalid):
-			c.JSON(http.StatusNotFound, gin.H{"error": i18n.LocalizedMessage(c, "error.share_code_invalid")})
-		case errors.Is(err, services.ErrShareCodeExpired):
-			c.JSON(http.StatusBadRequest, gin.H{"error": i18n.LocalizedMessage(c, "error.share_code_expired")})
-		case errors.Is(err, services.ErrUserAlreadyMember):
-			c.JSON(http.StatusConflict, gin.H{"error": i18n.LocalizedMessage(c, "error.user_already_member")})
-		default:
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		}
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, response)
+	return c.JSON(http.StatusOK, response)
 }
 
 // GetResidenceUsers handles GET /api/residences/:id/users/
-func (h *ResidenceHandler) GetResidenceUsers(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) GetResidenceUsers(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 
 	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": i18n.LocalizedMessage(c, "error.invalid_residence_id")})
-		return
+		return apperrors.BadRequest("error.invalid_residence_id")
 	}
 
 	users, err := h.residenceService.GetResidenceUsers(uint(residenceID), user.ID)
 	if err != nil {
-		switch {
-		case errors.Is(err, services.ErrResidenceNotFound):
-			c.JSON(http.StatusNotFound, gin.H{"error": i18n.LocalizedMessage(c, "error.residence_not_found")})
-		case errors.Is(err, services.ErrResidenceAccessDenied):
-			c.JSON(http.StatusForbidden, gin.H{"error": i18n.LocalizedMessage(c, "error.residence_access_denied")})
-		default:
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		}
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, users)
+	return c.JSON(http.StatusOK, users)
 }
 
 // RemoveResidenceUser handles DELETE /api/residences/:id/users/:user_id/
-func (h *ResidenceHandler) RemoveResidenceUser(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) RemoveResidenceUser(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 
 	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": i18n.LocalizedMessage(c, "error.invalid_residence_id")})
-		return
+		return apperrors.BadRequest("error.invalid_residence_id")
 	}
 
 	userIDToRemove, err := strconv.ParseUint(c.Param("user_id"), 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": i18n.LocalizedMessage(c, "error.invalid_user_id")})
-		return
+		return apperrors.BadRequest("error.invalid_user_id")
 	}
 
 	err = h.residenceService.RemoveUser(uint(residenceID), uint(userIDToRemove), user.ID)
 	if err != nil {
-		switch {
-		case errors.Is(err, services.ErrResidenceNotFound):
-			c.JSON(http.StatusNotFound, gin.H{"error": i18n.LocalizedMessage(c, "error.residence_not_found")})
-		case errors.Is(err, services.ErrNotResidenceOwner):
-			c.JSON(http.StatusForbidden, gin.H{"error": i18n.LocalizedMessage(c, "error.not_residence_owner")})
-		case errors.Is(err, services.ErrCannotRemoveOwner):
-			c.JSON(http.StatusBadRequest, gin.H{"error": i18n.LocalizedMessage(c, "error.cannot_remove_owner")})
-		default:
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		}
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, gin.H{"message": i18n.LocalizedMessage(c, "message.user_removed")})
+	return c.JSON(http.StatusOK, map[string]interface{}{"message": i18n.LocalizedMessage(c, "message.user_removed")})
 }
 
 // GetResidenceTypes handles GET /api/residences/types/
-func (h *ResidenceHandler) GetResidenceTypes(c *gin.Context) {
+func (h *ResidenceHandler) GetResidenceTypes(c echo.Context) error {
 	types, err := h.residenceService.GetResidenceTypes()
 	if err != nil {
-		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		return
+		return err
 	}
 
-	c.JSON(http.StatusOK, types)
+	return c.JSON(http.StatusOK, types)
 }
 
 // GenerateTasksReport handles POST /api/residences/:id/generate-tasks-report/
 // Generates a PDF report of tasks for the residence and emails it
-func (h *ResidenceHandler) GenerateTasksReport(c *gin.Context) {
-	user := c.MustGet(middleware.AuthUserKey).(*models.User)
+func (h *ResidenceHandler) GenerateTasksReport(c echo.Context) error {
+	user := c.Get(middleware.AuthUserKey).(*models.User)
 
 	residenceID, err := strconv.ParseUint(c.Param("id"), 10, 32)
 	if err != nil {
-		c.JSON(http.StatusBadRequest, gin.H{"error": i18n.LocalizedMessage(c, "error.invalid_residence_id")})
-		return
+		return apperrors.BadRequest("error.invalid_residence_id")
 	}
 
 	// Optional request body for email recipient
 	var req struct {
 		Email string `json:"email"`
 	}
-	c.ShouldBindJSON(&req)
+	c.Bind(&req)
 
 	// Generate the report data
 	report, err := h.residenceService.GenerateTasksReport(uint(residenceID), user.ID)
 	if err != nil {
-		switch {
-		case errors.Is(err, services.ErrResidenceNotFound):
-			c.JSON(http.StatusNotFound, gin.H{"error": i18n.LocalizedMessage(c, "error.residence_not_found")})
-		case errors.Is(err, services.ErrResidenceAccessDenied):
-			c.JSON(http.StatusForbidden, gin.H{"error": i18n.LocalizedMessage(c, "error.residence_access_denied")})
-		default:
-			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
-		}
-		return
+		return err
 	}
 
 	// Determine recipient email
@@ -415,7 +325,7 @@ func (h *ResidenceHandler) GenerateTasksReport(c *gin.Context) {
 		message = i18n.LocalizedMessage(c, "message.tasks_report_email_failed")
 	}
 
-	c.JSON(http.StatusOK, gin.H{
+	return c.JSON(http.StatusOK, map[string]interface{}{
 		"message":         message,
 		"residence_name":  report.ResidenceName,
 		"recipient_email": recipientEmail,