feat(mail): SRC-11 geschlossener FacetField-Typ statt Whitelist-Liste

fields.go: neuer Typ FacetField mit vier geschlossenen Konstanten
(FacetFieldSender/Mailbox/AttachmentType/Tag). IsValid() entscheidet
über ein erschöpfendes switch/case statt eine []string-Liste zu
durchsuchen — genau der aus known-issues-archivmail.md #12 und
known-issues-archivdms.md #10 bekannte Fehler (dynamische Tabellen-/
Feldnamen nur durch eine fragile Whitelist-Funktion abgesichert) wird
damit strukturell vermieden: ein vergessener Listeneintrag kann nichts
mehr durchlassen, weil es keine durchsuchte Liste mehr gibt.
ParseFacetField ist die einzige vorgesehene Konstruktionsstelle für
FacetField aus einer externen Zeichenkette.

facets.go: FacetFilter.Field ist jetzt FacetField statt string,
buildFilteredMust prüft f.Field.IsValid() statt Listenmitgliedschaft
(isFacetField entfernt, es gibt keine Liste mehr, die die Entscheidung
trifft).

Alle Pflichtprüfungen mit echten Nachweisen: unbekannte/erfundene
Facettenfelder werden abgelehnt, alle vier realen Facettenfelder
funktionieren weiterhin, ein FacetField-Wert per direkter
Typkonvertierung (nicht über ParseFacetField) wird trotzdem zuverlässig
abgelehnt (Akzeptanzkriterium 2: Whitelist ist nicht die einzige
Absicherung), automatisiertes Code-Review bestätigt kein fmt.Sprintf in
facets.go/fields.go. Entscheidung dokumentiert: Mail-eigene
Implementierung, keine geteilte Utility mit dem DMS-Board (Prüfprotokoll).

Keine Regression, insbesondere mail/internal/savedsearch (Konsument von
FacetFilter) unverändert grün — go build/go vet/golangci-lint clean,
gesamtes Mail-Modul regressionsfrei getestet.
This commit is contained in:
sysops
2026-09-01 14:01:34 +02:00
parent af1709a2bb
commit 4fdb424b23
4 changed files with 279 additions and 22 deletions
+14 -19
View File
@@ -14,11 +14,13 @@ import (
)
// FacetFilter schränkt Suche/Facettenberechnung auf einen bereits
// gewählten Facettenwert ein. Field MUSS aus FacetFields stammen —
// Facets liefert einen Fehler bei jedem anderen Wert (verhindert einen
// beliebigen, vom Aufrufer bestimmten Feldnamen in der Anfrage).
// gewählten Facettenwert ein. Field ist der geschlossene FacetField-Typ
// (SRC-11) — buildFilteredMust prüft zusätzlich FacetField.IsValid(),
// sodass selbst ein über json.Unmarshal aus der Datenbank
// rekonstruierter, nicht mehr gültiger Wert (z. B. nach Entfernen eines
// Feldes) abgelehnt wird statt stillschweigend durchzulaufen.
type FacetFilter struct {
Field string
Field FacetField
Value string
}
@@ -70,19 +72,12 @@ func dateRangeBoundaries(now time.Time) []dateRangeBoundary {
}
}
func isFacetField(field string) bool {
for _, f := range FacetFields {
if f == field {
return true
}
}
return false
}
// buildFilteredMust baut die gemeinsame bool.must-Liste für Facets und
// SearchWithFilters: Tenant-Filter zwingend, optionaler Suchtext, dann je
// Filter eine zusätzliche equals-Klausel (UND-Verknüpfung) — einzige
// Stelle, an der Filter-Feldnamen gegen FacetFields geprüft werden.
// Stelle, an der Filter-Feldnamen geprüft werden, über das geschlossene
// FacetField.IsValid() (SRC-11 Akzeptanzkriterium 2), nicht über eine
// durchsuchbare Liste.
func buildFilteredMust(tenantSlug, queryText string, filters []FacetFilter) ([]map[string]any, error) {
must := []map[string]any{
{"equals": map[string]any{FieldTenantSlug: tenantSlug}},
@@ -91,10 +86,10 @@ func buildFilteredMust(tenantSlug, queryText string, filters []FacetFilter) ([]m
must = append(must, map[string]any{"query_string": queryText})
}
for _, f := range filters {
if !isFacetField(f.Field) {
if !f.Field.IsValid() {
return nil, fmt.Errorf("search: unbekanntes facettenfeld %q", f.Field)
}
must = append(must, map[string]any{"equals": map[string]any{f.Field: f.Value}})
must = append(must, map[string]any{"equals": map[string]any{string(f.Field): f.Value}})
}
return must, nil
}
@@ -162,7 +157,7 @@ func (c *Client) Facets(ctx context.Context, tenantSlug, queryText string, filte
aggs := map[string]any{}
for _, field := range FacetFields {
aggs[field] = map[string]any{"terms": map[string]any{"field": field, "size": 100}}
aggs[string(field)] = map[string]any{"terms": map[string]any{"field": string(field), "size": 100}}
}
boundaries := dateRangeBoundaries(time.Now())
ranges := make([]map[string]any, 0, len(boundaries))
@@ -208,7 +203,7 @@ func (c *Client) Facets(ctx context.Context, tenantSlug, queryText string, filte
result := FacetResult{Values: make(map[string][]FacetValue, len(FacetFields))}
for _, field := range FacetFields {
bucket := parsed.Aggregations[field]
bucket := parsed.Aggregations[string(field)]
values := make([]FacetValue, 0, len(bucket.Buckets))
for _, b := range bucket.Buckets {
if b.Key == "" {
@@ -216,7 +211,7 @@ func (c *Client) Facets(ctx context.Context, tenantSlug, queryText string, filte
}
values = append(values, FacetValue{Value: b.Key, Count: b.DocCount})
}
result.Values[field] = values
result.Values[string(field)] = values
}
sentAtBucket := parsed.Aggregations["sent_at"]