chore: establish project baseline

2026-09-21 15:51:47 -03:00
commit 9dcc263217
459 changed files with 447890 additions and 0 deletions
@@ -0,0 +1,64 @@
+# Fiscal Data Foundation V1 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add isolated, versioned official fiscal-data ingestion without product tax determination.
+
+**Architecture:** A shared dataset lifecycle stores auditable metadata and retains active versions. Each domain parser/importer validates its own official payload and fails independently.
+
+**Tech Stack:** Python, SQLAlchemy, Alembic, FastAPI, pytest.
+
+## Global Constraints
+
+- Use only official primary sources.
+- Preserve existing NCM and CEST imports.
+- Never write to Firebird or classify products.
+- Failed imports cannot supersede active datasets.
+
+---
+
+### Task 1: Dataset Version Metadata
+
+**Files:**
+- Modify: `central/app/models.py`
+- Create: `central/alembic/versions/0003_dataset_foundation_metadata.py`
+- Test: `central/tests/test_dataset_lifecycle.py`
+
+- [ ] Write a failing test asserting `parser_version`, effective dates, raw reference, and failure reason persist.
+- [ ] Run `python -m pytest central/tests/test_dataset_lifecycle.py -q` and verify failure.
+- [ ] Add the model fields and migration.
+- [ ] Re-run the focused test and verify pass.
+
+### Task 2: Isolated Lifecycle Service
+
+**Files:**
+- Modify: `central/app/datasets/service.py`
+- Test: `central/tests/test_dataset_lifecycle.py`
+
+- [ ] Write failing tests for a failed replacement retaining its prior active dataset and for independent domains.
+- [ ] Run focused tests and verify failure.
+- [ ] Implement pending, failed, and active promotion methods scoped by domain.
+- [ ] Re-run focused tests and verify pass.
+
+### Task 3: Official Domain Importers
+
+**Files:**
+- Create: `central/app/datasets/foundation.py`
+- Create: `central/scripts/import_foundation.py`
+- Test: `central/tests/test_foundation_parsers.py`
+
+- [ ] Write failing parser tests for official structured payload validation and unsupported structures.
+- [ ] Run focused tests and verify failure.
+- [ ] Implement versioned fail-closed adapters for BA_ST_MVA, CFOP, CST_CSOSN, PIS_COFINS, TIPI_IPI, CCLASSTRIB_IBSCBS, FCP, and MONOFASICO_ICMS.
+- [ ] Re-run focused tests and verify pass.
+
+### Task 4: Active Dataset Smoke Matrix
+
+**Files:**
+- Modify: `central/app/api.py`
+- Test: `central/tests/test_dataset_status.py`
+
+- [ ] Write failing test for active-only dataset status with lifecycle metadata.
+- [ ] Run focused test and verify failure.
+- [ ] Add the active dataset status/smoke response.
+- [ ] Run `python -m pytest tests central/tests agent/tests -q` and verify pass.