feat(crm): Expediente — referencia única de trazabilidad del trámite (Fase D)

- Tabla crm.cases (expediente) con folio EXP2026-08-001 (next_folio entidad EXP,
  sin dirección). Nace al crear la Oportunidad y se hereda vía case_id a
  solicitud → cotización → operación → factura. advance_stage solo avanza.
- case_id (FK a crm.cases) en crm.opportunities/service_requests/quotes,
  ops.shipments y fin.invoices; propagación en sus create_*. Migración
  d4e5f6a7b8c9 reversible.
- Endpoints GET /v1/crm/cases, /cases/{id}, /cases/by-ref/{ref} con timeline
  (historia completa para UI y otros sistemas).
- Frontend: casesAPI, ruta /dashboard/crm/expedientes (lista + timeline vertical),
  chip "📁 Expediente" en solicitud/cotización, "Expedientes" en el sidebar.
- Consecutivo de folios sin tope (soporta >10,000,000/mes).
- 4 pruebas de expediente (minteo, propagación, timeline, no-retroceso). Suite en verde (113).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

backend/api/v1/modules/crm/cases/dto.py

@@ -0,0 +1,31 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class CaseResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    reference: str | None
+    account_id: int | None
+    title: str | None
+    stage: str
+    status: str
+    tenant_id: int
+    company_id: int
+    created_at: datetime
+    updated_at: datetime
+
+
+class CaseTimelineEvent(BaseModel):
+    kind: str            # oportunidad | solicitud | cotizacion | operacion | factura
+    id: int
+    reference: str | None = None
+    status: str | None = None
+    created_at: datetime
+    url: str
+
+
+class CaseWithTimeline(CaseResponse):
+    timeline: list[CaseTimelineEvent] = []

backend/api/v1/modules/crm/cases/models.py

@@ -0,0 +1,28 @@
+from sqlalchemy import ForeignKey, Integer, String, text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from api.v1.common.base_models import TenantScopedMixin, TimestampMixin
+from core.database import Base
+
+
+class Case(Base, TenantScopedMixin, TimestampMixin):
+    """Expediente: hilo maestro de un trámite (Oportunidad → Solicitud → Cotización →
+    Operación → Factura). Una sola referencia (``EXP…``) que agrupa toda la historia.
+    Nace al crear la Oportunidad y se hereda a las entidades siguientes vía ``case_id``.
+    """
+
+    __tablename__ = "cases"
+    __table_args__ = {"schema": "crm"}
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    reference: Mapped[str | None] = mapped_column(String(40), nullable=True, index=True)  # folio EXP...
+    account_id: Mapped[int | None] = mapped_column(
+        Integer, ForeignKey("crm.accounts.id"), nullable=True, index=True
+    )
+    title: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    # Etapa más avanzada alcanzada: oportunidad|solicitud|cotizacion|operacion|facturacion|cerrado
+    stage: Mapped[str] = mapped_column(String(20), nullable=False, server_default=text("'oportunidad'"))
+    # abierto | cerrado
+    status: Mapped[str] = mapped_column(String(20), nullable=False, server_default=text("'abierto'"), index=True)
+    created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)

backend/api/v1/modules/crm/cases/routes.py

@@ -0,0 +1,51 @@
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.orm import Session
+
+from core.database import get_core_db
+from core.security import get_current_user
+
+from . import service
+from .dto import CaseResponse, CaseWithTimeline
+
+router = APIRouter()
+
+
+def _with_timeline(db, case) -> CaseWithTimeline:
+    data = CaseWithTimeline.model_validate(case)
+    data.timeline = service.build_timeline(db, case)  # type: ignore[assignment]
+    return data
+
+
+@router.get("/cases", response_model=list[CaseResponse])
+def list_cases(
+    company_id: int = Query(..., description="Company ID"),
+    search: str | None = Query(None),
+    account_id: int | None = Query(None),
+    stage: str | None = Query(None),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    return service.get_cases(db, current_user["tenant_id"], company_id, search, account_id, stage)
+
+
+@router.get("/cases/by-ref/{reference}", response_model=CaseWithTimeline)
+def get_case_by_ref(
+    reference: str,
+    company_id: int = Query(..., description="Company ID"),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    """Expediente + historia completa por su referencia (para UI y otros sistemas)."""
+    case = service.get_case_by_reference(db, reference, current_user["tenant_id"], company_id)
+    return _with_timeline(db, case)
+
+
+@router.get("/cases/{case_id}", response_model=CaseWithTimeline)
+def get_case(
+    case_id: int,
+    company_id: int = Query(..., description="Company ID"),
+    current_user: dict = Depends(get_current_user),
+    db: Session = Depends(get_core_db),
+):
+    case = service.get_case(db, case_id, current_user["tenant_id"], company_id)
+    return _with_timeline(db, case)

backend/api/v1/modules/crm/cases/service.py

@@ -0,0 +1,109 @@
+"""Lógica del Expediente: minteo del folio, avance de etapa y armado del timeline."""
+
+from fastapi import HTTPException, status
+from sqlalchemy.orm import Session
+
+from ..common.folios import next_folio
+from .models import Case
+
+# Orden de etapas (solo se avanza, nunca retrocede)
+STAGE_ORDER = ["oportunidad", "solicitud", "cotizacion", "operacion", "facturacion", "cerrado"]
+
+
+def create_case(
+    db: Session, tenant_id: int, company_id: int, *, account_id: int | None = None,
+    title: str | None = None, stage: str = "oportunidad", user_id: str | None = None,
+) -> Case:
+    """Mintea un expediente con folio EXP... (sin commit; lo confirma quien lo invoca)."""
+    case = Case(
+        reference=next_folio(db, tenant_id, company_id, "EXP", None, with_direction=False),
+        account_id=account_id, title=title, stage=stage, status="abierto",
+        tenant_id=tenant_id, company_id=company_id, created_by=user_id, updated_by=user_id,
+    )
+    db.add(case)
+    db.flush()
+    return case
+
+
+def advance_stage(db: Session, case_id: int | None, stage: str) -> None:
+    """Avanza la etapa del expediente si la nueva es posterior a la actual."""
+    if not case_id or stage not in STAGE_ORDER:
+        return
+    case = db.query(Case).filter(Case.id == case_id).first()
+    if not case:
+        return
+    current = case.stage if case.stage in STAGE_ORDER else "oportunidad"
+    if STAGE_ORDER.index(stage) > STAGE_ORDER.index(current):
+        case.stage = stage
+
+
+def get_cases(
+    db: Session, tenant_id: int, company_id: int, search: str | None = None,
+    account_id: int | None = None, stage: str | None = None,
+) -> list[Case]:
+    q = db.query(Case).filter(
+        Case.tenant_id == tenant_id, Case.company_id == company_id, Case.deleted_at.is_(None),
+    )
+    if account_id is not None:
+        q = q.filter(Case.account_id == account_id)
+    if stage:
+        q = q.filter(Case.stage == stage)
+    if search:
+        q = q.filter(Case.reference.ilike(f"%{search}%"))
+    return q.order_by(Case.created_at.desc()).all()
+
+
+def get_case(db: Session, case_id: int, tenant_id: int, company_id: int) -> Case:
+    obj = (
+        db.query(Case)
+        .filter(Case.id == case_id, Case.tenant_id == tenant_id, Case.company_id == company_id, Case.deleted_at.is_(None))
+        .first()
+    )
+    if not obj:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Expediente no encontrado")
+    return obj
+
+
+def get_case_by_reference(db: Session, reference: str, tenant_id: int, company_id: int) -> Case:
+    obj = (
+        db.query(Case)
+        .filter(Case.reference == reference, Case.tenant_id == tenant_id, Case.company_id == company_id,
+                Case.deleted_at.is_(None))
+        .first()
+    )
+    if not obj:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Expediente no encontrado")
+    return obj
+
+
+def build_timeline(db: Session, case: Case) -> list[dict]:
+    """Devuelve la historia del expediente: todas las entidades ligadas por case_id,
+    en orden cronológico. Un único lookup para la UI y para otros sistemas."""
+    # Import local para evitar ciclos de importación entre módulos.
+    from ..opportunities.models import Opportunity
+    from ..quotes.models import Quote
+    from ..service_requests.models import ServiceRequest
+    from api.v1.modules.fin.invoices.models import Invoice
+    from api.v1.modules.ops.shipments.models import Shipment
+
+    events: list[dict] = []
+    specs = [
+        ("oportunidad", Opportunity, "/dashboard/crm/oportunidades"),
+        ("solicitud", ServiceRequest, "/dashboard/crm/solicitudes"),
+        ("cotizacion", Quote, "/dashboard/crm/cotizaciones"),
+        ("operacion", Shipment, "/dashboard/ops/embarques"),
+        ("factura", Invoice, "/dashboard/fin/facturas"),
+    ]
+    for kind, model, base_url in specs:
+        rows = db.query(model).filter(model.case_id == case.id, model.deleted_at.is_(None)).all()
+        for r in rows:
+            events.append({
+                "kind": kind,
+                "id": r.id,
+                "reference": getattr(r, "reference", None),
+                "status": getattr(r, "status", None),
+                "created_at": r.created_at,
+                "url": f"{base_url}/{r.id}",
+            })
+    events.sort(key=lambda e: e["created_at"])
+    return events

backend/api/v1/modules/crm/common/folios.py

@@ -21,8 +21,8 @@ from sqlalchemy.orm import Mapped, mapped_column
 from api.v1.common.base_models import BaseTimestampMixin, TenantScopedMixin
 from core.database import Base
 
-# Entidades válidas y su letra de folio (F = factura, sin dirección impo/expo).
-ENTITIES = ("O", "S", "C", "OP", "F")
+# Entidades válidas y su letra de folio (F = factura, EXP = expediente; sin dirección).
+ENTITIES = ("O", "S", "C", "OP", "F", "EXP")
 # Mapa dirección de operación → sufijo del folio.
 _DIRECTION_SUFFIX = {"importacion": "I", "exportacion": "E"}
 

backend/api/v1/modules/crm/opportunities/dto.py

@@ -69,6 +69,7 @@ class OpportunityResponse(BaseModel):
     notes: str | None
     operation_type: str | None = None
     reference: str | None = None
+    case_id: int | None = None
     converted_service_request_id: int | None = None
     tenant_id: int
     company_id: int

backend/api/v1/modules/crm/opportunities/models.py

@@ -43,6 +43,8 @@ class Opportunity(Base, TenantScopedMixin, TimestampMixin):
     # Dirección de la operación (importacion|exportacion): se hereda a Solicitud→Cotización→Embarque
     operation_type: Mapped[str | None] = mapped_column(String(20), nullable=True)
     reference: Mapped[str | None] = mapped_column(String(40), nullable=True, index=True)  # folio O...
+    # Expediente (hilo maestro del trámite); nace aquí y se hereda hacia abajo
+    case_id: Mapped[int | None] = mapped_column(Integer, ForeignKey("crm.cases.id"), nullable=True, index=True)
     # Solicitud generada al convertir la oportunidad (back-link idempotente)
     converted_service_request_id: Mapped[int | None] = mapped_column(
         Integer, ForeignKey("crm.service_requests.id"), nullable=True

backend/api/v1/modules/crm/opportunities/service.py

@@ -4,6 +4,7 @@ from fastapi import HTTPException, status
 from sqlalchemy.orm import Session
 
 from ..accounts.models import Account
+from ..cases import service as cases_service
 from ..common.folios import next_folio
 from ..contacts.models import Contact
 from ..pipelines.models import Pipeline, PipelineStage
@@ -159,6 +160,12 @@ def create_opportunity(
     # Folio O... auto-generado (mensual). La dirección impo/expo se hereda al ciclo.
     if not opportunity.reference:
         opportunity.reference = next_folio(db, tenant_id, company_id, "O", opportunity.operation_type)
+    # Expediente: nace con la oportunidad y se hereda a solicitud/cotización/operación/factura
+    if not opportunity.case_id:
+        case = cases_service.create_case(
+            db, tenant_id, company_id, account_id=opportunity.account_id, title=opportunity.name, stage="oportunidad",
+        )
+        opportunity.case_id = case.id
     db.add(opportunity)
     db.commit()
     db.refresh(opportunity)

backend/api/v1/modules/crm/quotes/dto.py

@@ -86,6 +86,7 @@ class QuoteResponse(QuoteBase):
 
     id: int
     service_request_reference: str | None = None  # folio de la solicitud referenciada
+    case_id: int | None = None
     status: str
     total_cost: Decimal
     total_sale: Decimal

backend/api/v1/modules/crm/quotes/models.py

@@ -15,6 +15,7 @@ class Quote(Base, TenantScopedMixin, TimestampMixin):
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
     reference: Mapped[str | None] = mapped_column(String(40), nullable=True, index=True)
+    case_id: Mapped[int | None] = mapped_column(Integer, ForeignKey("crm.cases.id"), nullable=True, index=True)  # expediente
     service_request_id: Mapped[int | None] = mapped_column(
         Integer, ForeignKey("crm.service_requests.id"), nullable=True, index=True
     )

backend/api/v1/modules/crm/quotes/service.py

@@ -6,6 +6,7 @@ from sqlalchemy import func
 from sqlalchemy.orm import Session
 
 from ..accounts.models import Account
+from ..cases import service as cases_service
 from ..catalogs.models import CatalogItem
 from ..common.folios import next_folio
 from ..common.pricing import air_chargeable_kg
@@ -123,6 +124,12 @@ def create_quote(
     # Folio C... auto-generado (mensual), con la dirección heredada de la solicitud
     if not obj.reference:
         obj.reference = next_folio(db, tenant_id, company_id, "C", _sr_direction(db, obj.service_request_id))
+    # Expediente heredado de la solicitud
+    if obj.service_request_id and not obj.case_id:
+        sr = db.query(ServiceRequest).filter(ServiceRequest.id == obj.service_request_id).first()
+        if sr:
+            obj.case_id = sr.case_id
+    cases_service.advance_stage(db, obj.case_id, "cotizacion")
     db.add(obj)
     db.commit()
     db.refresh(obj)
@@ -184,6 +191,7 @@ def create_quotes_from_service_request(
             notes=sr.client_notes or sr.notes,
             owner_user_id=sr.owner_user_id,
             reference=next_folio(db, tenant_id, company_id, "C", sr.operation_type),
+            case_id=sr.case_id,
             tenant_id=tenant_id,
             company_id=company_id,
             created_by=user_id,
@@ -225,6 +233,7 @@ def create_quotes_from_service_request(
         _recompute_totals(db, quote)
         created.append(quote)
 
+    cases_service.advance_stage(db, sr.case_id, "cotizacion")
     db.commit()
     for quote in created:
         db.refresh(quote)

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

@@ -13,6 +13,7 @@ from . import permissions  # noqa: F401  (side-effect: registra permisos del CRM
 from .accounts.routes import router as accounts_router
 from .activities.routes import router as activities_router
 from .addresses.routes import router as addresses_router
+from .cases.routes import router as cases_router
 from .catalogs.routes import router as catalogs_router
 from .contacts.routes import router as contacts_router
 from .documents.routes import router as documents_router
@@ -43,6 +44,7 @@ router.include_router(leads_router)
 router.include_router(pipelines_router)
 router.include_router(opportunities_router)
 router.include_router(activities_router)
+router.include_router(cases_router)
 router.include_router(metrics_router)
 router.include_router(catalogs_router)
 router.include_router(uploads_router)

backend/api/v1/modules/crm/service_requests/dto.py

@@ -162,6 +162,7 @@ class ServiceRequestResponse(ServiceRequestBase):
     model_config = ConfigDict(from_attributes=True)
 
     id: int
+    case_id: int | None = None
     first_contact_at: datetime | None = None
     first_contact_notes: str | None = None
     tenant_id: int

backend/api/v1/modules/crm/service_requests/models.py

@@ -19,6 +19,7 @@ class ServiceRequest(Base, TenantScopedMixin, TimestampMixin):
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
     reference: Mapped[str | None] = mapped_column(String(40), nullable=True, index=True)  # folio
+    case_id: Mapped[int | None] = mapped_column(Integer, ForeignKey("crm.cases.id"), nullable=True, index=True)  # expediente
     account_id: Mapped[int | None] = mapped_column(
         Integer, ForeignKey("crm.accounts.id"), nullable=True, index=True
     )

backend/api/v1/modules/crm/service_requests/service.py

@@ -4,6 +4,7 @@ from fastapi import HTTPException, status
 from sqlalchemy.orm import Session
 
 from ..accounts.models import Account
+from ..cases import service as cases_service
 from ..catalogs.data import INCOTERM_CODES
 from ..common.folios import next_folio
 from ..contacts.models import Contact
@@ -110,6 +111,12 @@ def create_service_request(
     # Folio S... auto-generado (mensual) si no viene uno explícito
     if not obj.reference:
         obj.reference = next_folio(db, tenant_id, company_id, "S", obj.operation_type)
+    # Expediente: normalmente nace en la oportunidad; si la solicitud es directa, se mintea aquí
+    if not obj.case_id:
+        case = cases_service.create_case(
+            db, tenant_id, company_id, account_id=obj.account_id, title=obj.reference, stage="solicitud", user_id=user_id,
+        )
+        obj.case_id = case.id
     db.add(obj)
     db.commit()
     db.refresh(obj)
@@ -200,6 +207,7 @@ def create_from_opportunity(
         notes=payload.notes,
         owner_user_id=opp.owner_user_id,
         reference=next_folio(db, tenant_id, company_id, "S", operation_type),
+        case_id=opp.case_id,
         tenant_id=tenant_id,
         company_id=company_id,
         created_by=user_id,
@@ -207,6 +215,13 @@ def create_from_opportunity(
     )
     db.add(obj)
     db.flush()
+    # Expediente heredado de la oportunidad (fallback si la oportunidad es antigua sin expediente)
+    if not obj.case_id:
+        obj.case_id = cases_service.create_case(
+            db, tenant_id, company_id, account_id=opp.account_id, title=obj.reference, stage="solicitud", user_id=user_id,
+        ).id
+        opp.case_id = obj.case_id
+    cases_service.advance_stage(db, obj.case_id, "solicitud")
     # Back-link para cerrar el ciclo Oportunidad→Solicitud (y garantizar idempotencia)
     opp.converted_service_request_id = obj.id
     db.commit()

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

@@ -100,6 +100,7 @@ class InvoiceResponse(InvoiceBase):
     model_config = ConfigDict(from_attributes=True)
 
     id: int
+    case_id: int | None = None
     status: str
     subtotal: Decimal
     tax_amount: Decimal

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

@@ -15,6 +15,7 @@ class Invoice(Base, TenantScopedMixin, TimestampMixin):
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
     reference: Mapped[str | None] = mapped_column(String(40), nullable=True, index=True)  # folio
+    case_id: Mapped[int | None] = mapped_column(Integer, ForeignKey("crm.cases.id"), nullable=True, index=True)  # expediente
     shipment_id: Mapped[int | None] = mapped_column(
         Integer, ForeignKey("ops.shipments.id"), nullable=True, index=True
     )

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

@@ -6,6 +6,7 @@ from sqlalchemy import func
 from sqlalchemy.orm import Session
 
 from api.v1.modules.crm.accounts.models import Account
+from api.v1.modules.crm.cases import service as cases_service
 from api.v1.modules.crm.common.folios import next_folio
 from api.v1.modules.crm.quotes.models import Quote, QuoteItem
 from api.v1.modules.ops.shipments.models import Shipment
@@ -99,6 +100,12 @@ def create_invoice(db, payload: InvoiceCreate, tenant_id, company_id, user_id=No
     # Folio F... auto-generado (mensual) si no viene uno explícito
     if not obj.reference:
         obj.reference = next_folio(db, tenant_id, company_id, "F", None, with_direction=False)
+    # Expediente heredado del embarque (si la factura se genera de uno)
+    if obj.shipment_id and not obj.case_id:
+        sh = db.query(Shipment).filter(Shipment.id == obj.shipment_id).first()
+        if sh:
+            obj.case_id = sh.case_id
+    cases_service.advance_stage(db, obj.case_id, "facturacion")
     db.add(obj)
     db.flush()
     _recompute(db, obj)
@@ -285,6 +292,7 @@ def generate_from_shipment(db, shipment_id, tenant_id, company_id, user_id=None)
 
     invoice = Invoice(
         reference=shipment.reference,
+        case_id=shipment.case_id,
         shipment_id=shipment.id,
         quote_id=shipment.quote_id,
         account_id=shipment.account_id,
@@ -298,6 +306,7 @@ def generate_from_shipment(db, shipment_id, tenant_id, company_id, user_id=None)
     )
     db.add(invoice)
     db.flush()
+    cases_service.advance_stage(db, shipment.case_id, "facturacion")
 
     if quote:
         q_items = db.query(QuoteItem).filter(QuoteItem.quote_id == quote.id, QuoteItem.deleted_at.is_(None)).all()

backend/api/v1/modules/ops/shipments/dto.py

@@ -82,6 +82,7 @@ class ShipmentResponse(ShipmentBase):
     model_config = ConfigDict(from_attributes=True)
 
     id: int
+    case_id: int | None = None
     closed_at: datetime | None = None
     closed_by: str | None = None
     created_by: str | None = None

backend/api/v1/modules/ops/shipments/models.py

@@ -15,6 +15,7 @@ class Shipment(Base, TenantScopedMixin, TimestampMixin):
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
     reference: Mapped[str | None] = mapped_column(String(40), nullable=True, index=True)  # folio de embarque
+    case_id: Mapped[int | None] = mapped_column(Integer, ForeignKey("crm.cases.id"), nullable=True, index=True)  # expediente
     quote_id: Mapped[int | None] = mapped_column(
         Integer, ForeignKey("crm.quotes.id"), nullable=True, index=True
     )

backend/api/v1/modules/ops/shipments/service.py

@@ -5,6 +5,7 @@ from sqlalchemy import func
 from sqlalchemy.orm import Session
 
 from api.v1.modules.crm.accounts.models import Account
+from api.v1.modules.crm.cases import service as cases_service
 from api.v1.modules.crm.common.folios import next_folio
 from api.v1.modules.crm.quotes.models import Quote
 from api.v1.modules.crm.service_requests.models import ServiceRequest
@@ -218,6 +219,7 @@ def create_shipment_from_quote(
 
     shipment = Shipment(
         reference=next_folio(db, tenant_id, company_id, "OP", resolved),
+        case_id=quote.case_id,
         quote_id=quote.id,
         service_request_id=quote.service_request_id,
         account_id=quote.account_id,
@@ -238,6 +240,7 @@ def create_shipment_from_quote(
     db.add(shipment)
     if sr:
         sr.status = "liberada"
+    cases_service.advance_stage(db, quote.case_id, "operacion")
     db.flush()
     # Siembra automática de hitos si ya se conoce la dirección de la operación
     for position, (event_type, title, kind) in enumerate(_DEFAULT_MILESTONES.get(resolved or "", [])):