feat(fin): amarre de facturas y partidas a catálogos SAT

fin.invoices gana tipo de comprobante, forma y método de pago y CP de
expedición; fin.invoice_items gana concepto de catálogo y las claves ProdServ,
unidad y objeto de impuesto. Todas nullable: las facturas ya emitidas no las
tienen y siguen funcionando igual (listado, detalle, PDF, envío).

La columna de texto libre invoice_items.concept se conserva obligatoria porque
la consume el PDF actual; al capturar por catálogo, el service hereda ahí la
descripción del concepto cuando el cliente no la envía.

Nueva tabla fin.invoice_item_taxes para el detalle de impuestos trasladados y
retenidos por partida. No interviene en el cálculo de subtotal/IVA/total, que
sigue saliendo de invoices.tax_rate.

Incluye la migración e6f7a8b9c0d1 (crea el schema sat, siembra los catálogos con
sync_catalogs y monta las tablas e índices nuevos) y registra los permisos
fin.concept.* y fin.settings.{view,edit}.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

backend/api/v1/modules/fin/invoices/dto.py

@@ -10,7 +10,16 @@ class InvoiceClientReviewInput(BaseModel):
     notes: str | None = None
 
 
-class InvoiceItemBase(BaseModel):
+class InvoiceItemSatFields(BaseModel):
+    """Claves fiscales de la partida. Opcionales: las facturas previas no las tienen."""
+
+    concept_id: int | None = None
+    product_service_id: int | None = None
+    unit_of_measure_id: int | None = None
+    tax_object_id: int | None = None
+
+
+class InvoiceItemBase(InvoiceItemSatFields):
     concept: str = Field(..., max_length=60)
     description: str | None = Field(None, max_length=255)
     quantity: Decimal = Field(Decimal(1), ge=0, max_digits=12, decimal_places=2)
@@ -19,9 +28,11 @@ class InvoiceItemBase(BaseModel):
 
 class InvoiceItemCreate(InvoiceItemBase):
     invoice_id: int
+    # Opcional solo si viene concept_id: el service copia la descripción del concepto.
+    concept: str | None = Field(None, max_length=60)
 
 
-class InvoiceItemUpdate(BaseModel):
+class InvoiceItemUpdate(InvoiceItemSatFields):
     concept: str | None = Field(None, max_length=60)
     description: str | None = Field(None, max_length=255)
     quantity: Decimal | None = Field(None, ge=0, max_digits=12, decimal_places=2)
@@ -76,6 +87,11 @@ class InvoiceBase(BaseModel):
     bank_info: str | None = None
     notes: str | None = None
     owner_user_id: str | None = Field(None, max_length=64)
+    # ----- Claves fiscales del CFDI (opcionales mientras no se timbre) -----
+    voucher_type_id: int | None = None
+    payment_form_id: int | None = None
+    payment_method_id: int | None = None
+    expedition_zip_code: str | None = Field(None, max_length=5)
 
 
 class InvoiceCreate(InvoiceBase):
@@ -94,6 +110,10 @@ class InvoiceUpdate(BaseModel):
     bank_info: str | None = None
     notes: str | None = None
     owner_user_id: str | None = Field(None, max_length=64)
+    voucher_type_id: int | None = None
+    payment_form_id: int | None = None
+    payment_method_id: int | None = None
+    expedition_zip_code: str | None = Field(None, max_length=5)
 
 
 class InvoiceResponse(InvoiceBase):

backend/api/v1/modules/fin/invoices/models.py

@@ -1,11 +1,22 @@
 from datetime import date, datetime
 
-from sqlalchemy import Boolean, Date, DateTime, ForeignKey, Integer, Numeric, String, Text, text
+from sqlalchemy import Boolean, Date, DateTime, ForeignKey, Index, Integer, Numeric, String, Text, text
 from sqlalchemy.orm import Mapped, mapped_column
 
 from api.v1.common.base_models import TenantScopedMixin, TimestampMixin
 from core.database import Base
 
+from ..catalogs.models import (  # noqa: F401  (registra los catálogos SAT referidos por las FK)
+    PaymentForm,
+    PaymentMethod,
+    ProductService,
+    Tax,
+    TaxObject,
+    UnitOfMeasure,
+    VoucherType,
+)
+from ..concepts.models import Concept  # noqa: F401
+
 
 class Invoice(Base, TenantScopedMixin, TimestampMixin):
     """Factura (Diagrama 4). Integra los costos de la operación para cobro al cliente."""
@@ -50,6 +61,18 @@ class Invoice(Base, TenantScopedMixin, TimestampMixin):
     owner_user_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
     created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
     updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    # ----- Datos fiscales del CFDI (catálogos SAT) -----
+    # Nullables: las facturas emitidas antes de existir los catálogos no los tienen.
+    voucher_type_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("sat.voucher_types.id"), nullable=True
+    )
+    payment_form_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("sat.payment_forms.id"), nullable=True
+    )
+    payment_method_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("sat.payment_methods.id"), nullable=True
+    )
+    expedition_zip_code: Mapped[str | None] = mapped_column(String(5), nullable=True)
 
 
 class InvoiceItem(Base, TenantScopedMixin, TimestampMixin):
@@ -62,10 +85,54 @@ class InvoiceItem(Base, TenantScopedMixin, TimestampMixin):
     invoice_id: Mapped[int] = mapped_column(
         Integer, ForeignKey("fin.invoices.id"), nullable=False, index=True
     )
+    # Texto libre histórico: lo consume el PDF actual y se conserva obligatorio.
     concept: Mapped[str] = mapped_column(String(60), nullable=False)
     description: Mapped[str | None] = mapped_column(String(255), nullable=True)
     quantity: Mapped[float] = mapped_column(Numeric(12, 2), nullable=False, server_default=text("1"))
     unit_amount: Mapped[float] = mapped_column(Numeric(14, 2), nullable=False, server_default=text("0"))
+    # ----- Datos fiscales de la partida (catálogos SAT) -----
+    concept_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("fin.concepts.id"), nullable=True, index=True
+    )
+    product_service_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("sat.products_services.id"), nullable=True
+    )
+    unit_of_measure_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("sat.units_of_measure.id"), nullable=True
+    )
+    tax_object_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("sat.tax_objects.id"), nullable=True
+    )
+
+
+class InvoiceItemTax(Base, TenantScopedMixin, TimestampMixin):
+    """Impuesto trasladado o retenido de una partida de la factura.
+
+    Es captura de detalle fiscal para el futuro CFDI: **no** interviene en el cálculo
+    de subtotal/IVA/total de la factura, que sigue saliendo de ``invoices.tax_rate``.
+    """
+
+    __tablename__ = "invoice_item_taxes"
+    __table_args__ = (
+        Index(
+            "uq_fin_invoice_item_taxes",
+            "invoice_item_id", "tax_id", "is_withholding",
+            unique=True,
+            postgresql_where=text("deleted_at IS NULL"),
+            sqlite_where=text("deleted_at IS NULL"),
+        ),
+        {"schema": "fin"},
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    invoice_item_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("fin.invoice_items.id"), nullable=False, index=True
+    )
+    tax_id: Mapped[int] = mapped_column(Integer, ForeignKey("sat.taxes.id"), nullable=False)
+    # false = trasladado (se cobra al cliente); true = retenido
+    is_withholding: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
+    rate: Mapped[float | None] = mapped_column(Numeric(8, 6), nullable=True)  # p. ej. 0.160000
+    amount: Mapped[float] = mapped_column(Numeric(14, 2), nullable=False, server_default=text("0"))
 
 
 class Payment(Base, TenantScopedMixin, TimestampMixin):

backend/api/v1/modules/fin/invoices/service.py

@@ -9,6 +9,7 @@ from api.v1.modules.crm.accounts.models import Account
 from api.v1.modules.crm.quotes.models import Quote, QuoteItem
 from api.v1.modules.ops.shipments.models import Shipment
 
+from ..concepts.models import Concept
 from .dto import (
     InvoiceClientReviewInput,
     InvoiceCreate,
@@ -331,9 +332,38 @@ def _get_item(db, item_id, tenant_id, company_id) -> InvoiceItem:
     return obj
 
 
+def _resolve_item_concept(db, data: dict, tenant_id, company_id) -> None:
+    """Completa ``concept`` a partir del concepto del catálogo cuando no se envió.
+
+    El PDF de la factura sigue leyendo la columna de texto libre ``concept``, así que
+    al capturar por catálogo se hereda ahí la descripción del concepto (recortada al
+    largo de la columna).
+    """
+    concept_id = data.get("concept_id")
+    if concept_id is not None:
+        catalog_concept = db.query(Concept).filter(
+            Concept.id == concept_id, Concept.tenant_id == tenant_id,
+            Concept.company_id == company_id, Concept.deleted_at.is_(None),
+        ).first()
+        if not catalog_concept:
+            raise HTTPException(
+                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+                detail="El concepto del catálogo no existe en esta empresa",
+            )
+        if not data.get("concept"):
+            data["concept"] = catalog_concept.description[:60]
+    if not data.get("concept"):
+        raise HTTPException(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            detail="La partida requiere un concepto o una referencia al catálogo de conceptos",
+        )
+
+
 def create_item(db, payload: InvoiceItemCreate, tenant_id, company_id) -> InvoiceItem:
     invoice = get_invoice(db, payload.invoice_id, tenant_id, company_id)
-    item = InvoiceItem(**payload.model_dump(), tenant_id=tenant_id, company_id=company_id)
+    data = payload.model_dump()
+    _resolve_item_concept(db, data, tenant_id, company_id)
+    item = InvoiceItem(**data, tenant_id=tenant_id, company_id=company_id)
     db.add(item)
     db.flush()
     _recompute(db, invoice)

backend/api/v1/modules/fin/permissions.py

@@ -3,7 +3,7 @@
 from api.v1.modules.core.permissions.registry import registry
 
 MODULE = "fin"
-_ENTITIES = [("invoice", "facturas"), ("payment", "pagos")]
+_ENTITIES = [("invoice", "facturas"), ("payment", "pagos"), ("concept", "conceptos")]
 _ACTIONS = [("view", "Ver"), ("create", "Crear"), ("edit", "Editar"), ("delete", "Eliminar")]
 
 
@@ -12,6 +12,11 @@ def register_permissions() -> None:
     for entity, label in _ENTITIES:
         for action, verb in _ACTIONS:
             registry.register(code=f"{MODULE}.{entity}.{action}", description=f"{verb} {label}", module=MODULE, action=action)
+    # Datos fiscales del emisor: es configuración de la empresa, no una entidad con CRUD,
+    # así que solo tiene ver/editar. Los catálogos del SAT no llevan permiso propio:
+    # son globales y de solo lectura, basta con fin.access.
+    registry.register(code=f"{MODULE}.settings.view", description="Ver datos fiscales del emisor", module=MODULE, action="view")
+    registry.register(code=f"{MODULE}.settings.edit", description="Editar datos fiscales del emisor", module=MODULE, action="edit")
 
 
 register_permissions()

backend/api/v1/modules/fin/router.py

@@ -5,8 +5,14 @@ from fastapi import APIRouter, Depends
 from api.v1.modules.core.permissions.dependencies import PermissionChecker
 
 from . import permissions  # noqa: F401  (side-effect: registra permisos)
+from .catalogs.routes import router as catalogs_router
+from .concepts.routes import router as concepts_router
 from .invoices.routes import router as invoices_router
+from .issuer.routes import router as issuer_router
 
 # Enforcement por área/carril (R-T-07): se exige fin.access para el módulo.
 router = APIRouter(dependencies=[Depends(PermissionChecker(["fin.access"]))])
+router.include_router(catalogs_router)
+router.include_router(concepts_router)
+router.include_router(issuer_router)
 router.include_router(invoices_router)