dmolinari/SIG-CM2.0
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

ADM-009: Tablas Fiscales (IVA + IIBB) — append-only versioned ref data #22

Merged
dmolinari merged 36 commits from feature/ADM-009 into main 2026-04-18 11:45:13 +00:00
Conversation 0 Commits 36 Files Changed 129 +11290 -15
dmolinari commented 2026-04-18 11:40:14 +00:00
Owner
Copy Link

Resumen

ADM-009 provee los maestros fiscales (TipoDeIva, IngresosBrutos) que alimentan toda la cadena de facturación. Implementado con pattern append-only versioned ref data para garantizar trazabilidad fiscal correcta en NC/ND sobre facturas históricas.

Scope (in)

BD — Migración V014

  • Tablas TipoDeIva + IngresosBrutos con Temporal Tables (SYSTEM_VERSIONING + retention 10 años).
  • Columna PredecesorId INT NULL con FK self para cadena de versiones.
  • Seed obligatorio: 4 TipoDeIva canónicos (EXENTO, NO_GRAVADO, IVA_105, IVA_21) + 24 provincias (23 INDEC + CABA).
  • Permiso administracion:fiscal:gestionar + asignación a rol admin.

Backend — Clean Architecture

  • Domain: entidades sealed + factories + NuevaVersion() retorna tupla (predecesora cerrada, nueva). Porcentaje/Alicuota INMUTABLES (no hay WithPorcentaje).
  • Application: 16 handlers CQRS (8 IVA + 8 IIBB) con TransactionScope(ReadCommitted, AsyncFlow) + IAuditLogger fail-closed.
  • Infrastructure: repos Dapper con raw SQL, OUTPUT INSERTED.Id, CTE recursivo con OPTION (MAXRECURSION 100) para historial, guard optimistic WHERE VigenciaHasta IS NULL en cierre de vigencia.
  • API: FiscalController con 16 endpoints (/api/v1/admin/fiscal/{iva,iibb}/*), defensa raw-body en PATCH contra Porcentaje/Alicuota, ExceptionFilter con contrato unificado { error, message }.

Frontend — Feature-sliced

  • src/web/src/features/fiscal/{iva,iibb}/ con TanStack Query (staleTime: 15_000) + react-hook-form + zod v4.
  • Modal "Editar" sin campo Porcentaje/Alicuota (UI-level enforcement de inmutabilidad).
  • Modal "Nueva vigencia" con preview + confirmación explícita + color distinto.
  • Tooltip de historial con single request al backend (no N+1).
  • Banner global de advertencia antes de mutaciones.
  • Tokens --warning-bg + --warning-border agregados al Design System (v2.5).

Scope (out — explícito)

  • Regla RNI 50% → DIFERIDA a issue #20. Bloquea FAC-*, NO a ADM-009. Requiere confirmación contable/legal.
  • Snapshot de Porcentaje en Presupuesto/Aviso → trabajo de FAC-/VTA-. Este PR deja contrato establecido: FAC-* debe guardar TipoDeIvaId como FK estable + Porcentaje como snapshot defensivo.
  • Código AFIP en TipoDeIva → se agrega cuando INT-001 lo consuma.
  • ADM-006 (Configuración Global) → independiente; ADM-009 no lo requiere.

Decisión arquitectónica clave — append-only

TipoDeIva.Porcentaje e IngresosBrutos.Alicuota son INMUTABLES una vez creados. Cambiar el valor numérico NO es un PATCH — es un POST /{iva|iibb}/{id}/nueva-version que:

  1. Crea nueva fila con PredecesorId = {id}.
  2. Cierra predecesora con VigenciaHasta = nuevaVigencia - 1 día.
  3. Registra evento de auditoría tipo_iva.nueva_version / ingresos_brutos.nueva_version.
  4. Todo en un TransactionScope atómico — fail-closed si audit throws.

Razón: una NC/ND en 2028 contra factura 2025 debe recalcular con la alícuota de 2025, no la vigente hoy. Append-only convierte TipoDeIvaId en token fiscal permanente que FAC-*/INT-001 pueden consumir ciegamente.

Tests

Suite Resultado
SIGCM2.Application.Tests 704 / 704 ✅
SIGCM2.Api.Tests 220 / 220 ✅
Frontend (Vitest + RTL + MSW) 275 / 275 ✅
TOTAL 1199 / 1199

TDD estricto: Red → Green → Refactor en cada capa. Incluye test de reflection que verifica que WithPorcentaje/WithAlicuota NO existen en las entidades (defensa en profundidad contra regresiones de mutabilidad).

Smoke E2E realizado

  • Login + JWT ✅
  • Create IVA_99 27% → 201 ✅
  • Nueva versión 28.5% vigente 2026-05-01 → 201 ✅
  • Historial → cadena [5, 6] con PredecesorId correcto ✅
  • PATCH con porcentaje en body → 409 inmutable_usar_nueva_version ✅
  • AuditEvent: 2 entradas (tipo_iva.create + tipo_iva.nueva_version) con actor + metadata ✅

⚠️ Acción requerida del reviewer

Antes de mergear — aplicar V014 en tu entorno local:

# Aplicar migración:
sqlcmd -S TECNICA3 -d SIGCM2 -i database/migrations/V014__create_tablas_fiscales.sql

# Para rollback si lo necesitás:
sqlcmd -S TECNICA3 -d SIGCM2 -i database/migrations/V014_ROLLBACK.sql

La base de tests SIGCM2_Test se aplica automáticamente vía SqlTestFixture.EnsureV014SchemaAsync().

Follow-ups abiertos (NO cerrar con este PR)

  • #20 — [ADM-009] OQ-008: definir si recargo RNI 50% vive en Configuracion o constante de dominio. Bloquea FAC-* hasta confirmación contable/legal.
  • #21 — [ADM-008] Migrar PuntoDeVentaForm a sintaxis Zod v4 (bug preexistente). Bug latente en main desde ADM-008. Este PR solo migra los 4 componentes fiscales de ADM-009.

Artefactos SDD (engram — project: sig-cm2)

Fase Topic key
Explore sdd/adm-009-tablas-fiscales/explore
Proposal v2 sdd/adm-009-tablas-fiscales/proposal
Spec sdd/adm-009-tablas-fiscales/spec
Design sdd/adm-009-tablas-fiscales/design
Tasks sdd/adm-009-tablas-fiscales/tasks
Apply progress sdd/adm-009-tablas-fiscales/apply-progress
Decisions sdd/adm-009-tablas-fiscales/decisions
Tech debt sdd/adm-009-tablas-fiscales/tech-debt

Métricas

  • 91 tasks SDD ejecutadas en 7 batches con Strict TDD.
  • 36 commits atómicos.
  • 2 tech debts eliminados en cleanup pre-merge (V014 seed PascalCase + V014MigrationTests filtros específicos).
  • 1 bug preexistente detectado y documentado como follow-up (#21).
## Resumen ADM-009 provee los maestros fiscales (`TipoDeIva`, `IngresosBrutos`) que alimentan toda la cadena de facturación. Implementado con pattern **append-only versioned ref data** para garantizar trazabilidad fiscal correcta en NC/ND sobre facturas históricas. ## Scope (in) **BD — Migración V014** - Tablas `TipoDeIva` + `IngresosBrutos` con Temporal Tables (SYSTEM_VERSIONING + retention 10 años). - Columna `PredecesorId INT NULL` con FK self para cadena de versiones. - Seed obligatorio: 4 TipoDeIva canónicos (EXENTO, NO_GRAVADO, IVA_105, IVA_21) + 24 provincias (23 INDEC + CABA). - Permiso `administracion:fiscal:gestionar` + asignación a rol `admin`. **Backend — Clean Architecture** - Domain: entidades sealed + factories + `NuevaVersion()` retorna tupla `(predecesora cerrada, nueva)`. `Porcentaje`/`Alicuota` INMUTABLES (no hay `WithPorcentaje`). - Application: 16 handlers CQRS (8 IVA + 8 IIBB) con `TransactionScope(ReadCommitted, AsyncFlow)` + `IAuditLogger` fail-closed. - Infrastructure: repos Dapper con raw SQL, `OUTPUT INSERTED.Id`, **CTE recursivo con `OPTION (MAXRECURSION 100)`** para historial, guard optimistic `WHERE VigenciaHasta IS NULL` en cierre de vigencia. - API: `FiscalController` con 16 endpoints (`/api/v1/admin/fiscal/{iva,iibb}/*`), **defensa raw-body** en PATCH contra `Porcentaje`/`Alicuota`, ExceptionFilter con contrato unificado `{ error, message }`. **Frontend — Feature-sliced** - `src/web/src/features/fiscal/{iva,iibb}/` con TanStack Query (`staleTime: 15_000`) + react-hook-form + zod v4. - Modal "Editar" **sin campo Porcentaje/Alicuota** (UI-level enforcement de inmutabilidad). - Modal "Nueva vigencia" con preview + confirmación explícita + color distinto. - Tooltip de historial con **single request** al backend (no N+1). - Banner global de advertencia antes de mutaciones. - Tokens `--warning-bg` + `--warning-border` agregados al Design System (v2.5). ## Scope (out — explícito) - **Regla RNI 50%** → DIFERIDA a issue #20. Bloquea FAC-*, NO a ADM-009. Requiere confirmación contable/legal. - **Snapshot de `Porcentaje` en Presupuesto/Aviso** → trabajo de FAC-*/VTA-*. Este PR deja contrato establecido: FAC-* debe guardar `TipoDeIvaId` como FK estable + `Porcentaje` como snapshot defensivo. - **Código AFIP en `TipoDeIva`** → se agrega cuando INT-001 lo consuma. - **ADM-006 (Configuración Global)** → independiente; ADM-009 no lo requiere. ## Decisión arquitectónica clave — append-only `TipoDeIva.Porcentaje` e `IngresosBrutos.Alicuota` son **INMUTABLES** una vez creados. Cambiar el valor numérico NO es un `PATCH` — es un `POST /{iva|iibb}/{id}/nueva-version` que: 1. Crea nueva fila con `PredecesorId = {id}`. 2. Cierra predecesora con `VigenciaHasta = nuevaVigencia - 1 día`. 3. Registra evento de auditoría `tipo_iva.nueva_version` / `ingresos_brutos.nueva_version`. 4. Todo en un `TransactionScope` atómico — fail-closed si audit throws. **Razón**: una NC/ND en 2028 contra factura 2025 debe recalcular con la alícuota de 2025, no la vigente hoy. Append-only convierte `TipoDeIvaId` en token fiscal permanente que FAC-*/INT-001 pueden consumir ciegamente. ## Tests | Suite | Resultado | |-------|-----------| | SIGCM2.Application.Tests | **704 / 704** ✅ | | SIGCM2.Api.Tests | **220 / 220** ✅ | | Frontend (Vitest + RTL + MSW) | **275 / 275** ✅ | | **TOTAL** | **1199 / 1199** | TDD estricto: Red → Green → Refactor en cada capa. Incluye test de **reflection** que verifica que `WithPorcentaje`/`WithAlicuota` NO existen en las entidades (defensa en profundidad contra regresiones de mutabilidad). ## Smoke E2E realizado - Login + JWT ✅ - Create IVA_99 27% → 201 ✅ - Nueva versión 28.5% vigente 2026-05-01 → 201 ✅ - Historial → cadena `[5, 6]` con `PredecesorId` correcto ✅ - `PATCH` con `porcentaje` en body → **409 `inmutable_usar_nueva_version`** ✅ - AuditEvent: 2 entradas (`tipo_iva.create` + `tipo_iva.nueva_version`) con actor + metadata ✅ ## ⚠️ Acción requerida del reviewer **Antes de mergear** — aplicar V014 en tu entorno local: ```bash # Aplicar migración: sqlcmd -S TECNICA3 -d SIGCM2 -i database/migrations/V014__create_tablas_fiscales.sql # Para rollback si lo necesitás: sqlcmd -S TECNICA3 -d SIGCM2 -i database/migrations/V014_ROLLBACK.sql ``` La base de tests `SIGCM2_Test` se aplica automáticamente vía `SqlTestFixture.EnsureV014SchemaAsync()`. ## Follow-ups abiertos (NO cerrar con este PR) - **#20** — `[ADM-009] OQ-008: definir si recargo RNI 50% vive en Configuracion o constante de dominio`. Bloquea FAC-* hasta confirmación contable/legal. - **#21** — `[ADM-008] Migrar PuntoDeVentaForm a sintaxis Zod v4 (bug preexistente)`. Bug latente en `main` desde ADM-008. Este PR solo migra los 4 componentes fiscales de ADM-009. ## Artefactos SDD (engram — project: `sig-cm2`) | Fase | Topic key | |------|-----------| | Explore | `sdd/adm-009-tablas-fiscales/explore` | | Proposal v2 | `sdd/adm-009-tablas-fiscales/proposal` | | Spec | `sdd/adm-009-tablas-fiscales/spec` | | Design | `sdd/adm-009-tablas-fiscales/design` | | Tasks | `sdd/adm-009-tablas-fiscales/tasks` | | Apply progress | `sdd/adm-009-tablas-fiscales/apply-progress` | | Decisions | `sdd/adm-009-tablas-fiscales/decisions` | | Tech debt | `sdd/adm-009-tablas-fiscales/tech-debt` | ## Métricas - **91 tasks SDD** ejecutadas en 7 batches con Strict TDD. - **36 commits atómicos**. - **2 tech debts** eliminados en cleanup pre-merge (V014 seed PascalCase + V014MigrationTests filtros específicos). - **1 bug preexistente detectado** y documentado como follow-up (#21).
dmolinari added 36 commits 2026-04-18 11:40:14 +00:00
test(adm-009): V014 migration integration tests (Red) 93664612d5
feat(adm-009): V014 create TipoDeIva + IngresosBrutos tables with SYSTEM_VERSIONING 58ff15a0c0
feat(adm-009): V014 seed 4 TipoDeIva + 24 IngresosBrutos + permiso fiscal:gestionar f4bd84c3f1
chore(adm-009): actualizar Respawner TablesToIgnore + conteos de permisos en tests existentes c6c4eda269
test(adm-009): ProvinciaArgentina enum tests (Red) 3ee0bf0724
feat(adm-009): ProvinciaArgentina enum with display mapping 98a4fea7c4
test(adm-009): TipoDeIva entity validation tests (Red) b16dd313ed
feat(adm-009): TipoDeIva sealed entity with factories f307306f91
test(adm-009): IngresosBrutos entity tests (Red) 87364ff8e6
feat(adm-009): IngresosBrutos sealed entity mirror of TipoDeIva 088f2303c1
test(adm-009): domain exceptions tests (Red) 4cb3eed21f
feat(adm-009): domain exceptions for fiscal entities f267e4f427
feat(adm-009): Permiso.AdministracionFiscalGestionar constant 1d051c93d6
feat(adm-009): ITipoDeIvaRepository + IIngresosBrutosRepository abstractions eead0a35cd
test(adm-009): TipoDeIva + IngresosBrutos handler tests (Red) 8db2b333c0
test(adm-009): IngresosBrutos handler tests mirror (Red) 2cd25e1036
feat(adm-009): TipoDeIva + IngresosBrutos handlers, DTOs, DI registration bd0c4deea7
test(adm-009): TipoDeIvaRepository + IngresosBrutosRepository integration tests (Red) 8e2d6bfb14
feat(adm-009): TipoDeIvaRepository + IngresosBrutosRepository Dapper implementations + DI registration 83dd680fa3
test(adm-009): FiscalController integration tests with JWT auth (Red→Green) 4544a000ae
feat(adm-009): Fiscal API DTOs (requests + responses + mapper) 25407583eb
feat(adm-009): FiscalController with raw-body Porcentaje/Alicuota defense b1a461b6cb
feat(adm-009): ExceptionFilter mapping for fiscal exceptions ({error, message} unified) 3eda59f5aa
chore(web): agregar tokens warning-bg y warning-border al Design System 9c05167788 
Tokens usados en banner de advertencia fiscal (ADM-009). Incluye variante
light (amber claro) y dark (amber oscuro), mapeados en @theme inline de Tailwind.
feat(web/adm-009): types y api client para fiscal IVA ea16d57646 
TipoDeIva types (UpdateRequest sin Porcentaje), ivaApi.ts con 8 endpoints,
ApiError contract { error, message } alineado con backend ADM-009.
feat(web/adm-009): hooks TanStack Query para fiscal IVA 95432e843f 
useTiposDeIvaList, useTipoDeIva, useHistorialTipoDeIva (lazy enable),
mutations con invalidateQueries. staleTime: 15_000 en todas las queries.
Query keys estables: ['fiscal', 'iva', ...].
test+feat(web/adm-009): TipoDeIvaTable con acciones y paginacion 8ffee0dbe4 
Columnas: Codigo, Descripcion, Porcentaje%, Vigencia (abierta si null),
Estado (badge), Version con HistorialCadenaTooltip lazy. Acciones: editar,
nueva vigencia, deactivate/reactivate toggle. 10 tests RTL pasan.
test+feat(web/adm-009): TipoDeIvaFormModal sin campo Porcentaje 038a2ade70 
Modal de edicion solo cosmeticos (Codigo, Descripcion, AplicaIVA, Activo).
Campo Porcentaje ausente en modo edit — verificado con queryByLabelText null [REQ-UI-003].
Modo create incluye Porcentaje inicial + VigenciaDesde. 10 tests RTL pasan.
test+feat(web/adm-009): NuevaVigenciaModal con preview de fechas 88274a9f10 
Preview en tiempo real: nuevo porcentaje, fecha cierre = vigenciaDesde-1d.
Banner warning con tokens DS. Boton disabled si form invalido [REQ-UI-004].
7 tests RTL pasan incluyendo verificacion de fecha cierre correcta.
test+feat(web/adm-009): TiposDeIvaPage con banner + tabla + modales fcd34081d2 
Banner advertencia visible al mount con tokens warning-bg/warning-border [REQ-UI-005].
Filtros por codigo y activo. Paginacion server-side. Modales create/edit/nueva-version
controlados por estado local. 12 tests RTL pasan.
test+feat(web/adm-009): iibb subfeature mirror de iva a3a15a4118 
Types (ProvinciaArgentina 24 valores + PROVINCIA_DISPLAY), iibbApi.ts,
useIngresosBrutos hooks, tabla con columna Provincia, FormModal sin Alicuota
en edit [REQ-UI-007], NuevaVigenciaIibbModal con preview, TiposDeIibbPage con
banner. 8 tests RTL pasan (iibb). Total fiscal: 47/47 tests.
chore(web): routes /admin/fiscal/iva y /admin/fiscal/iibb con permiso 4739e5cd46 
Ambas rutas protegidas con requiredPermissions=['administracion:fiscal:gestionar'].
Integradas en ProtectedPage con MustChangePasswordGate y ProtectedLayout.
chore(db): V014 seed Provincia en PascalCase (cleanup tech debt) 882f947765
refactor(infra): eliminar LegacySeedMap/NormalizeUpperSnakeToPascal de IngresosBrutosRepository 600ff52dd2
test(adm-009): V014MigrationTests con filtros especificos por seed (no count total) 8c08a706f0
fix(web/adm-009): migrar componentes fiscales a sintaxis Zod v4 30b55e60ea
dmolinari merged commit a804ef3c7b into main 2026-04-18 11:45:13 +00:00
dmolinari deleted branch feature/ADM-009 2026-04-18 11:45:13 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
followup
Deuda técnica o mejora detectada en un UDT, a retomar en otro futuro. Revisar al empezar cada UDT.
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
dmolinari
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: dmolinari/SIG-CM2.0#22
Delete Branch "feature/ADM-009"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?