feat: visible per-product enrichment status, flagged re-evaluation (panel/Reprocessar/Sincronizar/KB decision), operator NCM decision, deterministic name-only match, stale-write guard; 1.3.5

central/app/enrichment/kb.py

@@ -36,13 +36,39 @@ def find_by_gtin(session, key: str | None) -> KbProduct | None:
     return session.scalar(select(KbProduct).where(KbProduct.gtin == key)) if key else None
 
 
+NEUTRAL_EXTRAS = frozenset({"REFRIGERANTE", "REFRIG", "REFR", "BEBIDA", "PRODUTO", "PROD"})       # category nouns only: ZERO / DIET / a flavour / another size are NEVER neutral
+
+
+def _tokset(text) -> frozenset:
+    return frozenset(t for t in textnorm.tokens(text) if t not in textnorm.MARKETING)
+
+
+def alias_match(query: frozenset, alias: frozenset) -> bool:
+    """Deterministic, conservative: same token set, or one set contains the other and the difference is only neutral category nouns (so "COCA COLA LATA 350 ML" = "REFRIGERANTE COCA COLA LATA 350 ML", but not "... ZERO ...")."""
+    if not query or not alias:
+        return False
+    if query == alias:
+        return True
+    if query < alias:
+        return (alias - query) <= NEUTRAL_EXTRAS
+    if alias < query:
+        return (query - alias) <= NEUTRAL_EXTRAS
+    return False
+
+
 def name_candidates(session, description) -> list[KbProduct]:
-    """Exact-fingerprint matches (0, 1 or several)."""
+    """Every KB product with an alias that matches the description under `alias_match` (exact fingerprint included). 0, 1 or several - the caller decides (unique VERIFIED only)."""
     fp = textnorm.fingerprint(description)
     if not fp:
         return []
-    ids = list(session.scalars(select(KbKnowledge.kb_product_id).where(KbKnowledge.knowledge_key == "name_fingerprint", KbKnowledge.value == fp).distinct()))
-    return [p for p in (session.get(KbProduct, i) for i in ids) if p]
+    ids = set(session.scalars(select(KbKnowledge.kb_product_id).where(KbKnowledge.knowledge_key == "name_fingerprint", KbKnowledge.value == fp).distinct()))
+    query = _tokset(description)
+    anchor = max((t for t in query if not t.replace(".", "").isdigit() and len(t) > 2), key=len, default=None)      # most selective informative token, then verify in Python
+    if anchor:
+        for row in session.execute(select(KbKnowledge.kb_product_id, KbKnowledge.value).where(KbKnowledge.knowledge_key == "alias", KbKnowledge.value.contains(anchor))):
+            if alias_match(query, _tokset(row[1])):
+                ids.add(row[0])
+    return [p for p in (session.get(KbProduct, i) for i in sorted(ids)) if p]
 
 
 def upsert_product(session, key: str | None, description, *, brand=None, quantity=None) -> KbProduct:
@@ -140,6 +166,28 @@ def _mark(row, state):
     row.evidence = {**(row.evidence or {}), "info": {**((row.evidence or {}).get("info") or {}), "historical_state": state}}
 
 
+OPERATOR_FAMILY = "OPERATOR_ATTESTATION"
+
+
+def attest(session, gtin_key: str, ncm: str, operator: str, is_official, note: str = "") -> dict:
+    """A human fiscal decision by an ADMIN (audited by the caller). Only a value that is ALREADY a candidate in the KB (some local/provider evidence) and vigente in the official dataset can be attested;
+    the dissenting candidates become STALE (REJECTED_BY_OPERATOR) and the product is promoted with the promotion audit naming the operator."""
+    product = find_by_gtin(session, gtin_key)
+    if product is None:
+        raise ValueError("GTIN_UNKNOWN_IN_KB")
+    row = session.scalar(select(KbKnowledge).where(KbKnowledge.kb_product_id == product.id, KbKnowledge.knowledge_key == "ncm", KbKnowledge.value == ncm))
+    if row is None:
+        raise ValueError("NCM_IS_NOT_A_CANDIDATE_OF_THIS_GTIN")
+    if not is_official(ncm):
+        raise ValueError("NCM_NOT_VIGENTE_IN_OFFICIAL_DATASET")
+    add_evidence(session, product, "ncm", ncm, f"operator:{operator}"[:32], family=OPERATOR_FAMILY, info={"attested_by": operator, "attested_at": _now().isoformat(), "note": note[:200]})
+    for other in session.scalars(select(KbKnowledge).where(KbKnowledge.kb_product_id == product.id, KbKnowledge.knowledge_key == "ncm", KbKnowledge.value != ncm)):
+        if OPERATOR_FAMILY not in ((other.evidence or {}).get("families") or {}):
+            other.status = STALE
+            _mark(other, "REJECTED_BY_OPERATOR")
+    return evaluate(session, product, "ncm", is_official)
+
+
 def evaluate(session, product: KbProduct, key: str, is_official) -> dict:
     """Recomputes and PERSISTS the status of one field. Never 'majority wins': two current-valid values => CONFLICT."""
     rows = list(session.scalars(select(KbKnowledge).where(KbKnowledge.kb_product_id == product.id, KbKnowledge.knowledge_key == key)))
@@ -152,6 +200,14 @@ def evaluate(session, product: KbProduct, key: str, is_official) -> dict:
             state = _official_period(session, r.value) if key == "ncm" else "HISTORICAL_INVALID"
             r.status = STALE if state == "HISTORICAL_EXPIRED" else OBSERVED
             _mark(r, state)
+    attested = {r.value for r in valid if OPERATOR_FAMILY in ((r.evidence or {}).get("families") or {})}
+    if len(attested) == 1:                                                     # a human decision resolves the candidates: the others are recorded as rejected, not "outvoted"
+        winner = next(iter(attested))
+        for r in valid:
+            if r.value != winner:
+                r.status = STALE
+                _mark(r, "REJECTED_BY_OPERATOR")
+        valid = [r for r in valid if r.value == winner]
     values = sorted({r.value for r in valid})
     if len(values) > 1:
         for r in valid:
@@ -169,6 +225,9 @@ def evaluate(session, product: KbProduct, key: str, is_official) -> dict:
     if superseded and CLIENT_FAMILY in names:
         names.remove(CLIENT_FAMILY)
         count -= 1
+    if any(OPERATOR_FAMILY in ((r.evidence or {}).get("families") or {}) for r in chosen):
+        names = sorted(set(names) | {OPERATOR_FAMILY} | ({CLIENT_FAMILY} if any(CLIENT_FAMILY in ((r.evidence or {}).get("families") or {}) for r in chosen) else set()))
+        count = len(names)
     providers = [n for n in names if n.startswith("PROVIDER:")]
     already = any(r.status == VERIFIED_KB and r.validated_at for r in chosen)
     has_client_data = any(CLIENT_FAMILY in ((r.evidence or {}).get("families") or {}) for r in chosen)
@@ -188,7 +247,8 @@ def evaluate(session, product: KbProduct, key: str, is_official) -> dict:
     if status == VERIFIED_KB and old != VERIFIED_KB and key == "ncm":
         from .resolver import dataset_versions
         session.add(KbPromotionAudit(kb_product_id=product.id, gtin=product.gtin, field=key, value=values[0], old_status=old, new_status=status, families=names,
-                                     sources={"clients": summary["clients"], "documents": summary["docs"], "years": summary["years"], "providers": providers},
+                                     sources={"clients": summary["clients"], "documents": summary["docs"], "years": summary["years"], "providers": providers,
+                                                 "operator": next((((r.evidence or {}).get("info") or {}).get("attested_by") for r in chosen if OPERATOR_FAMILY in ((r.evidence or {}).get("families") or {})), None)},
                                      official_dataset=dataset_versions(session).get("NCM", {}), rule_version=RULE_VERSION))
     return {"value": values[0], "status": status, "families": names, "candidates": values, "rejected": rejected, "detail": summary}