fix: gate cClassTrib applicability by CRT and date

2026-09-25 17:47:04 -03:00
parent 95605c2ff5
commit 4a12640031
25 changed files with 498 additions and 72 deletions
@@ -0,0 +1,67 @@
+# cClassTrib applicability gate
+
+## Purpose
+
+Stop treating an empty `C000025.CCLASSTRIB` as a fiscal defect solely because
+the global RTC feature is enabled. Keep the single existing fiscal-completeness
+result and continue evaluating every other fiscal field normally.
+
+## Evidence and selected applicability rule
+
+The SGV database has `PARAMETROS.USAR_REFORMA_TRIBUTARIA=1` and RTC-capable
+schema, but the inspected `PARAMETROS` and `C000004` schemas have no separate
+cClassTrib enable flag. The SGV product screen exposes `C000025.CCLASSTRIB` as
+an editable catalog-backed field; available evidence does not mark it required
+for every product. The current code incorrectly promotes global RTC capability
+to universal per-product requiredness.
+
+Use the live company regime (`C000004.CRT`) together with the documented
+effective-date gate:
+
+- RTC capability/`USAR_REFORMA_TRIBUTARIA` must still be enabled for RTC
+  evaluation generally.
+- CRT 3: cClassTrib is applicable from 2026-08-03.
+- CRT 1, 2, or 4: cClassTrib is applicable from 2027-01-01.
+- Missing, conflicting, or unsupported CRT: cClassTrib is not applicable for
+  completeness until the company context is resolved; never infer a regime.
+- Before the applicable date, ignore cClassTrib completely: no blocker, no
+  candidate, no completeness penalty, and no write.
+- Once applicable, preserve the existing validation/resolution behavior,
+  including a blocker for an empty value when no safe resolution is available.
+
+This makes current Agent 2 (`CRT=1`, `OPTANTE_SIMPLES=S`) not applicable on
+2026-09-25 even though `USAR_REFORMA_TRIBUTARIA=1`. Its current RTC write mode
+(`DRY_RUN`) is not changed.
+
+## Minimal implementation boundary
+
+Add the gate to the existing shared fiscal evaluator/context using the already
+resolved live company CRT and current date. Do not add a new SGV flag, table,
+panel, or second coverage metric. Keep PIS/COFINS, NCM, resolver rules, RTC
+write authorization, and Agent write allowlist unchanged. Because the evaluator
+is executed by the Agent, this is an Agent code change. After test completion,
+the operator explicitly authorized release 1.2.5 through the official Hub/Agent
+deploy path and an in-place Agent 2 upgrade that preserves its identity.
+
+The RTC page should present the existing single-panel status as
+“cClassTrib: Não utilizado neste cliente” while the gate is false.
+
+## Verification
+
+Add the requested focused tests: not-applicable with empty cClassTrib (RTC off
+and on), unrelated fiscal fields still evaluated, applicable with empty
+cClassTrib still blocked, and zero write attempts. Then run a read-only
+`REPROCESS_ALL` against Agent 2 and compare its latest result/snapshot and
+blockers with the captured baseline. Preserve `RTC_WRITE_MODE=DRY_RUN` and
+verify Firebird write attempts/successes remain zero. Report NCM/PIS/COFINS
+blockers independently.
+
+## Baseline captured before implementation
+
+Agent 2 latest Hub snapshot/job: total 521, complete 0, safe-blocked 521,
+failed 0, unclassified 0, coverage 0%; RTC blockers 521; PIS blocker products
+1; COFINS blocker products 1; NCM blocker products 26 (29 open blocker rows).
+The offline read-only Firebird discovery saw `USAR_REFORMA_TRIBUTARIA=1`,
+`SISTEMA_TODO_FISCAL=0`, `C000004.CRT=1`, and
+`C000004.OPTANTE_SIMPLES='S'`; its guarded query recorded zero write attempts
+and zero successes.