honeyDueAPI/internal/services/suggestion_service.go

package services

import (
	"encoding/json"
	"sort"
	"strings"

	goi18n "github.com/nicksnyder/go-i18n/v2/i18n"
	"gorm.io/gorm"

	"github.com/treytartt/honeydue-api/internal/apperrors"
	"github.com/treytartt/honeydue-api/internal/dto/responses"
	"github.com/treytartt/honeydue-api/internal/i18n"
	"github.com/treytartt/honeydue-api/internal/models"
	"github.com/treytartt/honeydue-api/internal/repositories"
)

// SuggestionService handles residence-aware task template suggestions
type SuggestionService struct {
	db            *gorm.DB
	residenceRepo *repositories.ResidenceRepository
}

// NewSuggestionService creates a new suggestion service
func NewSuggestionService(db *gorm.DB, residenceRepo *repositories.ResidenceRepository) *SuggestionService {
	return &SuggestionService{
		db:            db,
		residenceRepo: residenceRepo,
	}
}

// stringList is a condition value that may be encoded as either a single JSON
// string ("gas_furnace") or an array of allowed strings (["gas_furnace",
// "boiler"]). The seeded template catalog uses arrays of allowed values; older
// hand-written conditions used a scalar. Accepting both keeps every existing
// condition working — and a scalar `*string` (the previous type) silently
// failed to unmarshal the array form, collapsing every conditioned template to
// "universal".
type stringList []string

// UnmarshalJSON accepts a string or an array of strings.
func (s *stringList) UnmarshalJSON(data []byte) error {
	var arr []string
	if err := json.Unmarshal(data, &arr); err == nil {
		*s = arr
		return nil
	}
	var one string
	if err := json.Unmarshal(data, &one); err != nil {
		return err
	}
	*s = stringList{one}
	return nil
}

// contains reports whether v is one of the allowed values.
func (s stringList) contains(v string) bool {
	for _, x := range s {
		if x == v {
			return true
		}
	}
	return false
}

// templateConditions represents the parsed conditions JSON from a task template.
// Every field is optional; a template with no conditions is "universal" and
// receives a small base score. See scoreTemplate for how each field is used.
type templateConditions struct {
	HeatingType     stringList `json:"heating_type,omitempty"`
	CoolingType     stringList `json:"cooling_type,omitempty"`
	WaterHeaterType stringList `json:"water_heater_type,omitempty"`
	RoofType        stringList `json:"roof_type,omitempty"`
	ExteriorType    stringList `json:"exterior_type,omitempty"`
	FlooringPrimary stringList `json:"flooring_primary,omitempty"`
	LandscapingType stringList `json:"landscaping_type,omitempty"`
	HasPool         *bool      `json:"has_pool,omitempty"`
	HasSprinkler    *bool      `json:"has_sprinkler_system,omitempty"`
	HasSeptic       *bool      `json:"has_septic,omitempty"`
	HasFireplace    *bool      `json:"has_fireplace,omitempty"`
	HasGarage       *bool      `json:"has_garage,omitempty"`
	HasBasement     *bool      `json:"has_basement,omitempty"`
	HasAttic        *bool      `json:"has_attic,omitempty"`
	PropertyType    stringList `json:"property_type,omitempty"`
	// ClimateRegionID replaces the old task_tasktemplate_regions join table.
	// Tag a template with the IECC zone ID it's relevant to (e.g. "Winterize
	// Sprinkler" → zone 5/6). Residence.PostalCode is mapped to a region at
	// scoring time via ZipToState + GetClimateRegionIDByState.
	ClimateRegionID *uint `json:"climate_region_id,omitempty"`
}

// isEmpty returns true if no conditions are set
func (c *templateConditions) isEmpty() bool {
	return len(c.HeatingType) == 0 && len(c.CoolingType) == 0 && len(c.WaterHeaterType) == 0 &&
		len(c.RoofType) == 0 && len(c.ExteriorType) == 0 && len(c.FlooringPrimary) == 0 &&
		len(c.LandscapingType) == 0 && c.HasPool == nil && c.HasSprinkler == nil &&
		c.HasSeptic == nil && c.HasFireplace == nil && c.HasGarage == nil &&
		c.HasBasement == nil && c.HasAttic == nil &&
		len(c.PropertyType) == 0 && c.ClimateRegionID == nil
}

const (
	maxSuggestions     = 30
	baseUniversalScore = 0.3
	stringMatchBonus   = 0.25
	boolMatchBonus     = 0.3
	// climateRegionBonus is deliberately higher than stringMatchBonus —
	// climate zone is coarse but high-signal (one bit for a whole region of
	// templates like "Hurricane Prep" or "Winterize Sprinkler").
	climateRegionBonus = 0.35
	propertyTypeBonus  = 0.15
	totalProfileFields = 15 // 14 home-profile fields + ZIP/region
)

// GetSuggestions returns task template suggestions scored against a residence's
// profile. Match reasons are localized for display via the supplied localizer
// (nil falls back to English).
func (s *SuggestionService) GetSuggestions(residenceID uint, userID uint, localizer *goi18n.Localizer) (*responses.TaskSuggestionsResponse, error) {
	// Check access
	hasAccess, err := s.residenceRepo.HasAccess(residenceID, userID)
	if err != nil {
		return nil, apperrors.Internal(err)
	}
	if !hasAccess {
		return nil, apperrors.Forbidden("error.residence_access_denied")
	}

	// Load residence
	residence, err := s.residenceRepo.FindByID(residenceID)
	if err != nil {
		return nil, apperrors.Internal(err)
	}

	// Load all active templates
	var templates []models.TaskTemplate
	if err := s.db.
		Preload("Category").
		Preload("Frequency").
		Where("is_active = ?", true).
		Find(&templates).Error; err != nil {
		return nil, apperrors.Internal(err)
	}

	// Score each template
	suggestions := make([]responses.TaskSuggestionResponse, 0, len(templates))
	for i := range templates {
		score, reasons, include := s.scoreTemplate(&templates[i], residence)
		if !include {
			continue
		}
		suggestions = append(suggestions, responses.TaskSuggestionResponse{
			Template:       responses.NewTaskTemplateResponse(&templates[i]),
			RelevanceScore: score,
			MatchReasons:   localizeReasons(localizer, reasons),
		})
	}

	// Sort by score descending
	sort.Slice(suggestions, func(i, j int) bool {
		return suggestions[i].RelevanceScore > suggestions[j].RelevanceScore
	})

	// Cap at maxSuggestions
	if len(suggestions) > maxSuggestions {
		suggestions = suggestions[:maxSuggestions]
	}

	completeness := CalculateProfileCompleteness(residence)

	return &responses.TaskSuggestionsResponse{
		Suggestions:         suggestions,
		TotalCount:          len(suggestions),
		ProfileCompleteness: completeness,
	}, nil
}

// localizeReasons converts the internal reason codes emitted by scoreTemplate
// into human-readable, localized strings for the API response.
//
// Codes come in two shapes: a bare feature code ("has_fireplace") and a
// "field:value" pair ("heating_type:gas_furnace"); for the latter we key off
// the field only (the percentage already conveys strength, and a per-enum-value
// catalog would be a much larger surface). The "universal" and "partial_profile"
// signals are internal scoring artifacts, not user-facing reasons, so they're
// dropped. Any code without a translation falls back to English so a raw key
// can never leak to the UI.
func localizeReasons(localizer *goi18n.Localizer, codes []string) []string {
	out := make([]string, 0, len(codes))
	for _, code := range codes {
		if code == "universal" || code == "partial_profile" {
			continue
		}
		field := code
		if i := strings.IndexByte(code, ':'); i >= 0 {
			field = code[:i]
		}
		key := "suggestion.reason." + field
		msg := i18n.T(localizer, key, nil)
		if msg == key {
			// Locale lacked the key — fall back to English so the user never
			// sees a raw message id.
			msg = i18n.T(i18n.NewLocalizer(i18n.DefaultLanguage), key, nil)
		}
		out = append(out, msg)
	}
	return out
}

// scoreTemplate scores a template against a residence profile.
// Returns (score, matchReasons, shouldInclude).
func (s *SuggestionService) scoreTemplate(tmpl *models.TaskTemplate, residence *models.Residence) (float64, []string, bool) {
	cond := &templateConditions{}

	// Parse conditions JSON
	if len(tmpl.Conditions) > 0 && string(tmpl.Conditions) != "{}" && string(tmpl.Conditions) != "null" {
		if err := json.Unmarshal(tmpl.Conditions, cond); err != nil {
			// Malformed conditions - treat as universal
			cond = &templateConditions{}
		}
	}

	// Universal template (no conditions): base score
	if cond.isEmpty() {
		return baseUniversalScore, []string{"universal"}, true
	}

	score := 0.0
	reasons := make([]string, 0)
	conditionCount := 0

	// String field matches. Each condition is a set of allowed values; the
	// residence matches when its value is one of them. A nil residence field is
	// ignored (no penalty, no exclusion); a mismatch simply earns no bonus.
	if len(cond.HeatingType) > 0 {
		conditionCount++
		if residence.HeatingType != nil && cond.HeatingType.contains(*residence.HeatingType) {
			score += stringMatchBonus
			reasons = append(reasons, "heating_type:"+*residence.HeatingType)
		}
	}

	if len(cond.CoolingType) > 0 {
		conditionCount++
		if residence.CoolingType != nil && cond.CoolingType.contains(*residence.CoolingType) {
			score += stringMatchBonus
			reasons = append(reasons, "cooling_type:"+*residence.CoolingType)
		}
	}

	if len(cond.WaterHeaterType) > 0 {
		conditionCount++
		if residence.WaterHeaterType != nil && cond.WaterHeaterType.contains(*residence.WaterHeaterType) {
			score += stringMatchBonus
			reasons = append(reasons, "water_heater_type:"+*residence.WaterHeaterType)
		}
	}

	if len(cond.RoofType) > 0 {
		conditionCount++
		if residence.RoofType != nil && cond.RoofType.contains(*residence.RoofType) {
			score += stringMatchBonus
			reasons = append(reasons, "roof_type:"+*residence.RoofType)
		}
	}

	if len(cond.ExteriorType) > 0 {
		conditionCount++
		if residence.ExteriorType != nil && cond.ExteriorType.contains(*residence.ExteriorType) {
			score += stringMatchBonus
			reasons = append(reasons, "exterior_type:"+*residence.ExteriorType)
		}
	}

	if len(cond.FlooringPrimary) > 0 {
		conditionCount++
		if residence.FlooringPrimary != nil && cond.FlooringPrimary.contains(*residence.FlooringPrimary) {
			score += stringMatchBonus
			reasons = append(reasons, "flooring_primary:"+*residence.FlooringPrimary)
		}
	}

	if len(cond.LandscapingType) > 0 {
		conditionCount++
		if residence.LandscapingType != nil && cond.LandscapingType.contains(*residence.LandscapingType) {
			score += stringMatchBonus
			reasons = append(reasons, "landscaping_type:"+*residence.LandscapingType)
		}
	}

	// Bool field matches - exclude if requires true but residence has false
	if cond.HasPool != nil {
		conditionCount++
		if *cond.HasPool && !residence.HasPool {
			return 0, nil, false // EXCLUDE
		}
		if *cond.HasPool && residence.HasPool {
			score += boolMatchBonus
			reasons = append(reasons, "has_pool")
		}
	}

	if cond.HasSprinkler != nil {
		conditionCount++
		if *cond.HasSprinkler && !residence.HasSprinklerSystem {
			return 0, nil, false
		}
		if *cond.HasSprinkler && residence.HasSprinklerSystem {
			score += boolMatchBonus
			reasons = append(reasons, "has_sprinkler_system")
		}
	}

	if cond.HasSeptic != nil {
		conditionCount++
		if *cond.HasSeptic && !residence.HasSeptic {
			return 0, nil, false
		}
		if *cond.HasSeptic && residence.HasSeptic {
			score += boolMatchBonus
			reasons = append(reasons, "has_septic")
		}
	}

	if cond.HasFireplace != nil {
		conditionCount++
		if *cond.HasFireplace && !residence.HasFireplace {
			return 0, nil, false
		}
		if *cond.HasFireplace && residence.HasFireplace {
			score += boolMatchBonus
			reasons = append(reasons, "has_fireplace")
		}
	}

	if cond.HasGarage != nil {
		conditionCount++
		if *cond.HasGarage && !residence.HasGarage {
			return 0, nil, false
		}
		if *cond.HasGarage && residence.HasGarage {
			score += boolMatchBonus
			reasons = append(reasons, "has_garage")
		}
	}

	if cond.HasBasement != nil {
		conditionCount++
		if *cond.HasBasement && !residence.HasBasement {
			return 0, nil, false
		}
		if *cond.HasBasement && residence.HasBasement {
			score += boolMatchBonus
			reasons = append(reasons, "has_basement")
		}
	}

	if cond.HasAttic != nil {
		conditionCount++
		if *cond.HasAttic && !residence.HasAttic {
			return 0, nil, false
		}
		if *cond.HasAttic && residence.HasAttic {
			score += boolMatchBonus
			reasons = append(reasons, "has_attic")
		}
	}

	// Property type match
	if len(cond.PropertyType) > 0 {
		conditionCount++
		if residence.PropertyType != nil && cond.PropertyType.contains(residence.PropertyType.Name) {
			score += propertyTypeBonus
			reasons = append(reasons, "property_type:"+residence.PropertyType.Name)
		}
	}

	// Climate region match. We resolve the residence's ZIP to a region ID on
	// demand; a missing/invalid ZIP is treated the same as a nil home-profile
	// field — no penalty, no exclusion.
	if cond.ClimateRegionID != nil {
		conditionCount++
		if residenceRegionID := resolveResidenceRegionID(residence); residenceRegionID != 0 && residenceRegionID == *cond.ClimateRegionID {
			score += climateRegionBonus
			reasons = append(reasons, "climate_region")
		}
	}

	// If template has conditions but none matched (residence fields unset or
	// different), rank it just below universal — it's a conditioned template we
	// couldn't confirm applies.
	if conditionCount > 0 && len(reasons) == 0 {
		return baseUniversalScore * 0.5, []string{"partial_profile"}, true
	}

	// A matched conditioned template must rank ABOVE a universal one. Anchor it
	// at the universal baseline and add the accumulated match bonuses on top,
	// so e.g. a single heating match (0.3 + 0.25) clearly beats universal (0.3).
	final := baseUniversalScore + score
	if final > 1.0 {
		final = 1.0
	}

	return final, reasons, true
}

// CalculateProfileCompleteness returns how many of the 14 home profile fields are filled
func CalculateProfileCompleteness(residence *models.Residence) float64 {
	filled := 0

	if residence.HeatingType != nil {
		filled++
	}
	if residence.CoolingType != nil {
		filled++
	}
	if residence.WaterHeaterType != nil {
		filled++
	}
	if residence.RoofType != nil {
		filled++
	}
	if residence.HasPool {
		filled++
	}
	if residence.HasSprinklerSystem {
		filled++
	}
	if residence.HasSeptic {
		filled++
	}
	if residence.HasFireplace {
		filled++
	}
	if residence.HasGarage {
		filled++
	}
	if residence.HasBasement {
		filled++
	}
	if residence.HasAttic {
		filled++
	}
	if residence.ExteriorType != nil {
		filled++
	}
	if residence.FlooringPrimary != nil {
		filled++
	}
	if residence.LandscapingType != nil {
		filled++
	}
	// PostalCode is the 15th field — counts toward completeness when we can
	// map it to a region. An invalid / unknown ZIP doesn't count.
	if resolveResidenceRegionIDByZip(residence.PostalCode) != 0 {
		filled++
	}

	return float64(filled) / float64(totalProfileFields)
}

// resolveResidenceRegionID returns the IECC climate zone ID for a residence
// based on its PostalCode, or 0 if the ZIP can't be mapped. Helper lives here
// (not in region_lookup.go) because it couples the Residence model to the
// suggestion service's notion of region resolution.
func resolveResidenceRegionID(residence *models.Residence) uint {
	return resolveResidenceRegionIDByZip(residence.PostalCode)
}

func resolveResidenceRegionIDByZip(zip string) uint {
	if zip == "" {
		return 0
	}
	state := ZipToState(zip)
	if state == "" {
		return 0
	}
	return GetClimateRegionIDByState(state)
}