i18n: backend-localized lookups, suggestions, and static data (10 languages)

- suggestion_service: fix scorer (stringList unmarshal accepts scalar|array; anchor scoring on base universal score so bool matches no longer tie); add localizeReasons for human-readable, Accept-Language-localized match reasons - lookup_i18n: localize lookup display names, home-profile options, document types/categories via internal/i18n - static_data_handler: per-locale seeded-data response (display_name, home profile options, document types/categories) with per-locale cache + ETag - settings_handler: invalidate per-locale seeded-data cache on lookup change instead of pre-warming a single non-localized blob - cache_service: per-locale seeded-data keys + ETag - DTOs: add DisplayName fields (task/residence/contractor) - translations: add suggestion.reason.* and lookup.* keys across all 10 langs - cmd/api: extract startup helpers + tests Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-04 20:54:54 -05:00
parent 25897e913e
commit 12de5a230a
23 changed files with 1671 additions and 703 deletions
@@ -47,12 +47,12 @@ func TestSuggestionService_UniversalTemplate(t *testing.T) {
 	// Create universal template (empty conditions)
 	createTemplateWithConditions(t, service, "Change Air Filters", nil)

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
 	assert.Equal(t, "Change Air Filters", resp.Suggestions[0].Template.Title)
 	assert.Equal(t, baseUniversalScore, resp.Suggestions[0].RelevanceScore)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "universal")
+	assert.Empty(t, resp.Suggestions[0].MatchReasons) // universal templates carry no display reason
 }

 func TestSuggestionService_HeatingTypeMatch(t *testing.T) {
@@ -75,11 +75,47 @@ func TestSuggestionService_HeatingTypeMatch(t *testing.T) {
 		"heating_type": "gas_furnace",
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
-	assert.Equal(t, stringMatchBonus, resp.Suggestions[0].RelevanceScore)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "heating_type:gas_furnace")
+	// Matched conditioned templates are anchored at the universal baseline and
+	// earn bonuses on top, so a match always ranks above a universal template.
+	assert.Equal(t, baseUniversalScore+stringMatchBonus, resp.Suggestions[0].RelevanceScore)
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Matches your heating system")
+}
+
+// TestSuggestionService_StringConditionArrayForm is the regression test for the
+// scorer bug where conditions encoded as an array of allowed values
+// (`{"heating_type":["gas_furnace","boiler"]}`, the format used by the seeded
+// template catalog) failed to unmarshal into a scalar *string field and the
+// template silently collapsed to "universal". The residence's value must match
+// when it is any member of the array.
+func TestSuggestionService_StringConditionArrayForm(t *testing.T) {
+	service := setupSuggestionService(t)
+	user := testutil.CreateTestUser(t, service.db, "owner", "owner@test.com", "password")
+
+	heatingType := "boiler" // second value in the allowed list
+	residence := &models.Residence{
+		OwnerID:     user.ID,
+		Name:        "Boiler House",
+		IsActive:    true,
+		IsPrimary:   true,
+		HeatingType: &heatingType,
+	}
+	require.NoError(t, service.db.Create(residence).Error)
+
+	// Array-of-allowed-values form, exactly as the seed catalog stores it.
+	createTemplateWithConditions(t, service, "Test Gas Shutoffs", map[string]interface{}{
+		"heating_type": []string{"gas_furnace", "boiler"},
+	})
+
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
+	require.NoError(t, err)
+	require.Len(t, resp.Suggestions, 1)
+	// Must MATCH (not fall back to universal) and rank above the universal baseline.
+	assert.Equal(t, baseUniversalScore+stringMatchBonus, resp.Suggestions[0].RelevanceScore)
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Matches your heating system")
+	assert.Len(t, resp.Suggestions[0].MatchReasons, 1)
 }

 func TestSuggestionService_ExcludedWhenPoolRequiredButFalse(t *testing.T) {
@@ -94,7 +130,7 @@ func TestSuggestionService_ExcludedWhenPoolRequiredButFalse(t *testing.T) {
 		"has_pool": true,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	assert.Len(t, resp.Suggestions, 0) // Should be excluded
 }
@@ -111,11 +147,11 @@ func TestSuggestionService_NilFieldIgnored(t *testing.T) {
 		"heating_type": "gas_furnace",
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
 	// Should be included (not excluded) but with low partial score
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "partial_profile")
+	assert.Empty(t, resp.Suggestions[0].MatchReasons) // conditioned-but-unmatched carries no display reason
 }

 func TestSuggestionService_ProfileCompleteness(t *testing.T) {
@@ -140,7 +176,7 @@ func TestSuggestionService_ProfileCompleteness(t *testing.T) {
 	// Create at least one template so we get a response
 	createTemplateWithConditions(t, service, "Universal Task", nil)

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	// 4 fields filled out of 15 (home-profile fields + ZIP/region)
 	expectedCompleteness := 4.0 / float64(totalProfileFields)
@@ -176,7 +212,7 @@ func TestSuggestionService_SortedByScoreDescending(t *testing.T) {
 		"has_pool": true,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 3)

@@ -193,7 +229,7 @@ func TestSuggestionService_AccessDenied(t *testing.T) {

 	residence := testutil.CreateTestResidence(t, service.db, owner.ID, "Private House")

-	_, err := service.GetSuggestions(residence.ID, stranger.ID)
+	_, err := service.GetSuggestions(residence.ID, stranger.ID, nil)
 	require.Error(t, err)
 	testutil.AssertAppErrorCode(t, err, 403)
 }
@@ -222,12 +258,13 @@ func TestSuggestionService_MultipleConditionsAllMustMatch(t *testing.T) {
 		"heating_type": "gas_furnace",
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)

-	// All three conditions matched
-	expectedScore := boolMatchBonus + boolMatchBonus + stringMatchBonus // 0.3 + 0.3 + 0.25 = 0.85
+	// All three conditions matched. Anchored baseline (0.3) + 0.3 + 0.3 + 0.25
+	// = 1.15, capped at 1.0.
+	expectedScore := 1.0
 	assert.InDelta(t, expectedScore, resp.Suggestions[0].RelevanceScore, 0.01)
 	assert.Len(t, resp.Suggestions[0].MatchReasons, 3)
 }
@@ -248,7 +285,7 @@ func TestSuggestionService_MalformedConditions(t *testing.T) {
 	err := service.db.Create(tmpl).Error
 	require.NoError(t, err)

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
 	// Should be treated as universal
@@ -270,7 +307,7 @@ func TestSuggestionService_NullConditions(t *testing.T) {
 	err := service.db.Create(tmpl).Error
 	require.NoError(t, err)

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
 	assert.Equal(t, baseUniversalScore, resp.Suggestions[0].RelevanceScore)
@@ -304,10 +341,10 @@ func TestSuggestionService_PropertyTypeMatch(t *testing.T) {
 		"property_type": "House",
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "property_type:House")
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Recommended for your property type")
 }

 // === CalculateProfileCompleteness with fully filled profile ===
@@ -392,7 +429,7 @@ func TestSuggestionService_ScoreCappedAtOne(t *testing.T) {
 		"has_garage":        true,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
 	assert.LessOrEqual(t, resp.Suggestions[0].RelevanceScore, 1.0)
@@ -409,7 +446,7 @@ func TestSuggestionService_InactiveTemplateExcluded(t *testing.T) {
 	err := service.db.Exec("INSERT INTO task_tasktemplate (title, is_active, conditions, created_at, updated_at) VALUES ('Inactive Task', false, '{}', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)").Error
 	require.NoError(t, err)

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	assert.Len(t, resp.Suggestions, 0)
 }
@@ -425,7 +462,7 @@ func TestSuggestionService_ExcludedWhenSprinklerRequired(t *testing.T) {
 		"has_sprinkler_system": true,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	assert.Len(t, resp.Suggestions, 0)
 }
@@ -441,7 +478,7 @@ func TestSuggestionService_ExcludedWhenSepticRequired(t *testing.T) {
 		"has_septic": true,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	assert.Len(t, resp.Suggestions, 0)
 }
@@ -455,7 +492,7 @@ func TestSuggestionService_ExcludedWhenFireplaceRequired(t *testing.T) {
 		"has_fireplace": true,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	assert.Len(t, resp.Suggestions, 0)
 }
@@ -469,7 +506,7 @@ func TestSuggestionService_ExcludedWhenGarageRequired(t *testing.T) {
 		"has_garage": true,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	assert.Len(t, resp.Suggestions, 0)
 }
@@ -483,7 +520,7 @@ func TestSuggestionService_ExcludedWhenBasementRequired(t *testing.T) {
 		"has_basement": true,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	assert.Len(t, resp.Suggestions, 0)
 }
@@ -497,7 +534,7 @@ func TestSuggestionService_ExcludedWhenAtticRequired(t *testing.T) {
 		"has_attic": true,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	assert.Len(t, resp.Suggestions, 0)
 }
@@ -523,10 +560,10 @@ func TestSuggestionService_CoolingTypeMatch(t *testing.T) {
 		"cooling_type": "central_ac",
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "cooling_type:central_ac")
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Matches your cooling system")
 }

 func TestSuggestionService_WaterHeaterTypeMatch(t *testing.T) {
@@ -548,10 +585,10 @@ func TestSuggestionService_WaterHeaterTypeMatch(t *testing.T) {
 		"water_heater_type": "tank_gas",
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "water_heater_type:tank_gas")
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Matches your water heater")
 }

 func TestSuggestionService_ExteriorTypeMatch(t *testing.T) {
@@ -573,10 +610,10 @@ func TestSuggestionService_ExteriorTypeMatch(t *testing.T) {
 		"exterior_type": "brick",
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "exterior_type:brick")
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Matches your exterior")
 }

 func TestSuggestionService_FlooringPrimaryMatch(t *testing.T) {
@@ -598,10 +635,10 @@ func TestSuggestionService_FlooringPrimaryMatch(t *testing.T) {
 		"flooring_primary": "hardwood",
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "flooring_primary:hardwood")
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Matches your flooring")
 }

 func TestSuggestionService_LandscapingTypeMatch(t *testing.T) {
@@ -623,10 +660,10 @@ func TestSuggestionService_LandscapingTypeMatch(t *testing.T) {
 		"landscaping_type": "lawn",
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "landscaping_type:lawn")
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Matches your landscaping")
 }

 func TestSuggestionService_RoofTypeMatch(t *testing.T) {
@@ -648,10 +685,10 @@ func TestSuggestionService_RoofTypeMatch(t *testing.T) {
 		"roof_type": "asphalt_shingle",
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "roof_type:asphalt_shingle")
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Matches your roof")
 }

 // === Mismatch on string field — no score for that field ===
@@ -676,11 +713,11 @@ func TestSuggestionService_HeatingTypeMismatch(t *testing.T) {
 		"heating_type": "gas_furnace",
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
 	// Should still be included but with partial_profile (no match, no exclude)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "partial_profile")
+	assert.Empty(t, resp.Suggestions[0].MatchReasons) // conditioned-but-unmatched carries no display reason
 }

 // === templateConditions.isEmpty ===
@@ -689,16 +726,14 @@ func TestTemplateConditions_IsEmpty(t *testing.T) {
 	cond := &templateConditions{}
 	assert.True(t, cond.isEmpty())

-	ht := "gas"
-	cond2 := &templateConditions{HeatingType: &ht}
+	cond2 := &templateConditions{HeatingType: stringList{"gas"}}
 	assert.False(t, cond2.isEmpty())

 	pool := true
 	cond3 := &templateConditions{HasPool: &pool}
 	assert.False(t, cond3.isEmpty())

-	pt := "House"
-	cond4 := &templateConditions{PropertyType: &pt}
+	cond4 := &templateConditions{PropertyType: stringList{"House"}}
 	assert.False(t, cond4.isEmpty())

 	var regionID uint = 5
@@ -727,11 +762,11 @@ func TestSuggestionService_ClimateRegionMatch(t *testing.T) {
 		"climate_region_id": 5,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
-	assert.InDelta(t, climateRegionBonus, resp.Suggestions[0].RelevanceScore, 0.001)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "climate_region")
+	assert.InDelta(t, baseUniversalScore+climateRegionBonus, resp.Suggestions[0].RelevanceScore, 0.001)
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Recommended for your climate")
 }

 func TestSuggestionService_ClimateRegionMismatch(t *testing.T) {
@@ -753,11 +788,11 @@ func TestSuggestionService_ClimateRegionMismatch(t *testing.T) {
 		"climate_region_id": 6,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1) // Still included — mismatch doesn't exclude
 	assert.InDelta(t, baseUniversalScore*0.5, resp.Suggestions[0].RelevanceScore, 0.001)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "partial_profile")
+	assert.Empty(t, resp.Suggestions[0].MatchReasons) // conditioned-but-unmatched carries no display reason
 }

 func TestSuggestionService_ClimateRegionIgnoredWhenNoZip(t *testing.T) {
@@ -779,7 +814,7 @@ func TestSuggestionService_ClimateRegionIgnoredWhenNoZip(t *testing.T) {
 		"climate_region_id": 5,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1) // Still included, just no bonus
 	assert.InDelta(t, baseUniversalScore*0.5, resp.Suggestions[0].RelevanceScore, 0.001)
@@ -802,11 +837,11 @@ func TestSuggestionService_ClimateRegionUnknownZip(t *testing.T) {
 		"climate_region_id": 5,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
 	// Unknown ZIP → 0 region → no match, but no crash
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "partial_profile")
+	assert.Empty(t, resp.Suggestions[0].MatchReasons) // conditioned-but-unmatched carries no display reason
 }

 func TestSuggestionService_ClimateRegionStacksWithOtherConditions(t *testing.T) {
@@ -829,11 +864,11 @@ func TestSuggestionService_ClimateRegionStacksWithOtherConditions(t *testing.T)
 		"climate_region_id": 5,
 	})

-	resp, err := service.GetSuggestions(residence.ID, user.ID)
+	resp, err := service.GetSuggestions(residence.ID, user.ID, nil)
 	require.NoError(t, err)
 	require.Len(t, resp.Suggestions, 1)
 	// Both bonuses should apply: stringMatchBonus + climateRegionBonus
-	assert.InDelta(t, stringMatchBonus+climateRegionBonus, resp.Suggestions[0].RelevanceScore, 0.001)
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "heating_type:gas_furnace")
-	assert.Contains(t, resp.Suggestions[0].MatchReasons, "climate_region")
+	assert.InDelta(t, baseUniversalScore+stringMatchBonus+climateRegionBonus, resp.Suggestions[0].RelevanceScore, 0.001)
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Matches your heating system")
+	assert.Contains(t, resp.Suggestions[0].MatchReasons, "Recommended for your climate")
 }