ADUANASOFT/CRM_AGENTES_CARGA
10
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/main' into feature/crm-cumplimiento-pdf

Browse Source 
Tres conflictos en frontend, todos por adiciones en el mismo punto:

- crm/types.ts y sidebar/modules.ts: se conservan las dos partes.
- crm/AccountFields.svelte: main pasó toda la pestaña fiscal a selects de crmCatalogs.
  Régimen fiscal y uso de CFDI se quedan con los catálogos del SAT (tax_regime_id /
  cfdi_use_id), que son las claves que viajan en el CFDI y que el PAC valida contra
  c_RegimenFiscal y c_UsoCFDI; el catálogo configurable del CRM no las garantiza. Método
  de pago, forma de pago y moneda sí toman la versión de main.

Las tres resoluciones son idénticas a las de feature/AS-timbrado-cfdi-ingreso, donde este
mismo merge ya se resolvió y se verificó, para que las dos ramas no diverjan de criterio.

Además, un choque que git no detecta: las dos ramas salieron de d5e6f7a8b9c0 y crearon una
migración con el mismo id, e6f7a8b9c0d1 —catálogos SAT aquí, catalog_items del CRM en
main—. Los archivos se llaman distinto, así que el merge pasa limpio y el problema sólo
aparece al arrancar Alembic, con la revisión duplicada y dos cabezas. Se renumera la de
facturación a g1h2i3j4k5l6 y se encadena detrás del carril EFC (c5d6e7f8a9b0).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jair Cedillo
2026-08-11 09:42:24 -05:00
parent e32c9f110e 926a75c5f8
commit 061b48d30f
175 changed files with 14108 additions and 673 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
backend/api/v1/modules/crm/accounts/dto.py
View File

@@ -13,15 +13,18 @@ class AccountBase(BaseModel):
record_type: str = Field("cliente", max_length=20) # cliente | prospecto
person_type: str | None = Field(None, max_length=10) # fisica | moral
industry: str | None = Field(None, max_length=120)
industry_other: str | None = Field(None, max_length=120)
account_type: str | None = Field(None, max_length=40)
status: str = Field("active", max_length=20) # active | inactive
# Comercial
commercial_classification: str | None = Field(None, max_length=20)
preferred_contact_method: str | None = Field(None, max_length=20)
preferred_contact_other: str | None = Field(None, max_length=120)
language: str | None = Field(None, max_length=40)
email: EmailStr | None = None
phone: str | None = Field(None, max_length=40)
website: str | None = Field(None, max_length=255)
commercial_observations: str | None = None # observaciones generales
# Fiscal
tax_regime: str | None = Field(None, max_length=120)
cfdi_use: str | None = Field(None, max_length=60)
@@ -39,7 +42,7 @@ class AccountBase(BaseModel):
address: str | None = None
city: str | None = Field(None, max_length=120)
state: str | None = Field(None, max_length=120)
country: str | None = Field("MX", max_length=2)
country: str | None = Field("MEX", max_length=3)
# Observaciones
notes: str | None = None
internal_notes: str | None = None
@@ -58,14 +61,17 @@ class AccountUpdate(BaseModel):
record_type: str | None = Field(None, max_length=20)
person_type: str | None = Field(None, max_length=10)
industry: str | None = Field(None, max_length=120)
industry_other: str | None = Field(None, max_length=120)
account_type: str | None = Field(None, max_length=40)
status: str | None = Field(None, max_length=20)
commercial_classification: str | None = Field(None, max_length=20)
preferred_contact_method: str | None = Field(None, max_length=20)
preferred_contact_other: str | None = Field(None, max_length=120)
language: str | None = Field(None, max_length=40)
email: EmailStr | None = None
phone: str | None = Field(None, max_length=40)
website: str | None = Field(None, max_length=255)
commercial_observations: str | None = None
tax_regime: str | None = Field(None, max_length=120)
cfdi_use: str | None = Field(None, max_length=60)
tax_regime_id: int | None = None
@@ -80,7 +86,7 @@ class AccountUpdate(BaseModel):
address: str | None = None
city: str | None = Field(None, max_length=120)
state: str | None = Field(None, max_length=120)
country: str | None = Field(None, max_length=2)
country: str | None = Field(None, max_length=3)
notes: str | None = None
internal_notes: str | None = None
owner_user_id: str | None = Field(None, max_length=64)

8
backend/api/v1/modules/crm/accounts/models.py
View File

@@ -32,6 +32,7 @@ class Account(Base, TenantScopedMixin, TimestampMixin):
# Tipo de persona: fisica | moral
person_type: Mapped[str | None] = mapped_column(String(10), nullable=True)
industry: Mapped[str | None] = mapped_column(String(120), nullable=True) # giro / industria
industry_other: Mapped[str | None] = mapped_column(String(120), nullable=True) # especificar cuando giro = "otro"
# Tipo operativo (immex | agencia_aduanal | importador | exportador | transportista | otro)
account_type: Mapped[str | None] = mapped_column(String(40), nullable=True)
# Estatus: active | inactive
@@ -40,12 +41,15 @@ class Account(Base, TenantScopedMixin, TimestampMixin):
# ----- Información comercial -----
# Clasificación: importador | exportador | ambos
commercial_classification: Mapped[str | None] = mapped_column(String(20), nullable=True)
# Medio de contacto preferido: llamada | correo | videollamada | whatsapp | otro
# Medio de contacto preferido: llamada | correo | videoconferencia | whatsapp | otro
preferred_contact_method: Mapped[str | None] = mapped_column(String(20), nullable=True)
# Texto libre cuando el medio de contacto es "otro"
preferred_contact_other: Mapped[str | None] = mapped_column(String(120), nullable=True)
language: Mapped[str | None] = mapped_column(String(40), nullable=True)
email: Mapped[str | None] = mapped_column(String(255), nullable=True)
phone: Mapped[str | None] = mapped_column(String(40), nullable=True)
website: Mapped[str | None] = mapped_column(String(255), nullable=True)
commercial_observations: Mapped[str | None] = mapped_column(Text, nullable=True) # observaciones generales
# ----- Información fiscal -----
# Régimen fiscal y uso de CFDI en texto libre: se conservan como capturó el usuario
@@ -72,7 +76,7 @@ class Account(Base, TenantScopedMixin, TimestampMixin):
address: Mapped[str | None] = mapped_column(Text, nullable=True)
city: Mapped[str | None] = mapped_column(String(120), nullable=True)
state: Mapped[str | None] = mapped_column(String(120), nullable=True)
country: Mapped[str | None] = mapped_column(String(2), nullable=True, server_default=text("'MX'"))
country: Mapped[str | None] = mapped_column(String(3), nullable=True, server_default=text("'MEX'"))
# ----- Observaciones y auditoría -----
notes: Mapped[str | None] = mapped_column(Text, nullable=True) # comentarios generales

4
backend/api/v1/modules/crm/addresses/dto.py
View File

@@ -14,7 +14,7 @@ class AddressBase(BaseModel):
postal_code: str | None = Field(None, max_length=10)
city: str | None = Field(None, max_length=120)
state: str | None = Field(None, max_length=120)
country: str | None = Field("MX", max_length=2)
country: str | None = Field("MEX", max_length=3) # ISO 3166-1 alfa-3 (alineado a catálogo pais)
reference_notes: str | None = None
is_primary: bool = False
@@ -32,7 +32,7 @@ class AddressUpdate(BaseModel):
postal_code: str | None = Field(None, max_length=10)
city: str | None = Field(None, max_length=120)
state: str | None = Field(None, max_length=120)
country: str | None = Field(None, max_length=2)
country: str | None = Field(None, max_length=3)
reference_notes: str | None = None
is_primary: bool | None = None

5
backend/api/v1/modules/crm/addresses/models.py
View File

@@ -29,7 +29,8 @@ class Address(Base, TenantScopedMixin, TimestampMixin):
neighborhood: Mapped[str | None] = mapped_column(String(120), nullable=True) # colonia
postal_code: Mapped[str | None] = mapped_column(String(10), nullable=True) # código postal
city: Mapped[str | None] = mapped_column(String(120), nullable=True) # municipio
state: Mapped[str | None] = mapped_column(String(120), nullable=True) # estado
country: Mapped[str | None] = mapped_column(String(2), nullable=True, server_default=text("'MX'"))
state: Mapped[str | None] = mapped_column(String(120), nullable=True) # estado (código catálogo)
# País como código ISO 3166 alfa-3 del catálogo (p. ej. MEX). Ampliado de 2→3.
country: Mapped[str | None] = mapped_column(String(3), nullable=True, server_default=text("'MEX'"))
reference_notes: Mapped[str | None] = mapped_column(Text, nullable=True) # referencias
is_primary: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))

0
backend/api/v1/modules/crm/cases/__init__.py Normal file
View File

31
backend/api/v1/modules/crm/cases/dto.py Normal file
View File

@@ -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] = []

52
backend/api/v1/modules/crm/cases/models.py Normal file
View File

@@ -0,0 +1,52 @@
from sqlalchemy import ForeignKey, Integer, String, Text, 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)
# ── Espejo del carril hacia EFC (T2026-08-046) ──────────────────────────────────────────
# EFC es la fuente única de los documentos del expediente: cada expediente se refleja allá
# como un *pedimento provisional* y los archivos viven en su MinIO, no en el del CRM.
#
# Estas columnas son un ESPEJO, nunca el handle. El handle con el que el CRM habla de este
# expediente es su ``id`` y su ``reference``: ``efc_pedimento_id`` es un caché de la
# resolución, y del lado de EFC el ``pedimento_app`` es mutable —se reescribe al completar
# el provisional con la data aduanera real—, así que apoyarse en él rompería justo cuando
# llegue esa data. La liga vive en EFC, en la tabla desechable ``pedimento_expediente``.
efc_organizacion_id: Mapped[str | None] = mapped_column(String(36), nullable=True)
efc_pedimento_id: Mapped[str | None] = mapped_column(String(36), nullable=True)
# INMUTABLE una vez asignado: es la carpeta de MinIO donde EFC guarda los objetos de este
# expediente. Que no cambie nunca es lo que permite completar el pedimento sin mover ni un
# archivo.
efc_storage_token: Mapped[str | None] = mapped_column(String(25), nullable=True)
# PENDING | LINKED | FAILED
efc_link_state: Mapped[str] = mapped_column(
String(20), nullable=False, server_default=text("'PENDING'"), index=True
)
# El diagnóstico se guarda en la fila para que se vea en la ficha del expediente, sin
# obligar a nadie a ir a los logs del worker.
efc_error_code: Mapped[str | None] = mapped_column(String(60), nullable=True)
efc_error_detail: Mapped[str | None] = mapped_column(Text, nullable=True)

51
backend/api/v1/modules/crm/cases/routes.py Normal file
View File

@@ -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)

130
backend/api/v1/modules/crm/cases/service.py Normal file
View File

@@ -0,0 +1,130 @@
"""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()
# ── Carril hacia EFC (T2026-08-046) ──────────────────────────────────────────────────
# EFC es la fuente única de los documentos del expediente. El reflejo allá —un pedimento
# provisional— se pide AQUÍ, en el instante en que nace el folio, porque el folio es
# precisamente la llave con la que las dos mitades se reconocen.
#
# El token de almacenamiento se fija al nacer y NO cambia nunca: es la carpeta de MinIO
# del lado de EFC. Que sea inmutable es lo que permite completar el provisional con la
# data aduanera real sin mover un solo archivo.
#
# Todo es best-effort y va en la MISMA transacción que el expediente:
# - con ``EFC_API_URL`` vacía es un no-op y el expediente vive igual, solo en el CRM;
# - si el encolado o el despacho fallan, no se propaga el error: el barrido del beat
# recoge lo pendiente. Un sistema de terceros caído no puede romper un alta.
# El import es diferido para no acoplar el arranque del módulo del expediente al carril.
from ..expediente_gateway import service as gateway
from ..expediente_gateway.storage import storage_token
case.efc_storage_token = storage_token(company_id, case.reference)
db.flush()
gateway.replicate_expediente_best_effort(db, case)
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

46
backend/api/v1/modules/crm/catalogs/dto.py Normal file
View File

@@ -0,0 +1,46 @@
"""Schemas (DTOs) de los catálogos de referencia del CRM."""
from pydantic import BaseModel, ConfigDict, Field
class CatalogItemBase(BaseModel):
code: str = Field(..., max_length=64)
label: str = Field(..., max_length=255)
parent_catalog: str | None = Field(None, max_length=60)
parent_code: str | None = Field(None, max_length=64)
sort_order: int = 0
is_active: bool = True
class CatalogItemCreate(CatalogItemBase):
pass
class CatalogItemUpdate(BaseModel):
"""PATCH: todos los campos opcionales."""
code: str | None = Field(None, max_length=64)
label: str | None = Field(None, max_length=255)
parent_code: str | None = Field(None, max_length=64)
sort_order: int | None = None
is_active: bool | None = None
class CatalogItemResponse(CatalogItemBase):
model_config = ConfigDict(from_attributes=True)
id: int
catalog: str
tenant_id: int | None
is_system: bool
extra: dict | None = None # metadata (ej. dimensiones de un tipo de equipo)
class CatalogMeta(BaseModel):
"""Metadata de un catálogo para la pantalla de administración."""
catalog: str
label: str
scope: str # 'global' | 'tenant'
is_system: bool
count: int

54
backend/api/v1/modules/crm/catalogs/models.py Normal file
View File

@@ -0,0 +1,54 @@
"""Modelo de catálogos de referencia del CRM (T2026-07-081/082).
Un único modelo genérico ``CatalogItem`` respalda todos los catálogos
(SAT/ISO y los propios del cliente). Cada fila pertenece a un catálogo
(``catalog``) e identifica una opción por ``code`` (clave) + ``label``
(descripción que se visualiza).
Alcance:
- ``tenant_id IS NULL`` → catálogo GLOBAL (Aduanasoft), compartido por todos.
- ``tenant_id`` con valor → catálogo del CLIENTE (ese tenant lo administra).
Los catálogos dependientes (p. ej. Estado depende de País) usan
``parent_catalog`` + ``parent_code`` para filtrarse.
"""
from datetime import datetime
from sqlalchemy import JSON, Boolean, DateTime, Integer, String, text
from sqlalchemy.orm import Mapped, mapped_column
from sqlalchemy.sql import func
from core.database import Base
class CatalogItem(Base):
__tablename__ = "catalog_items"
__table_args__ = {"schema": "crm"}
id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
catalog: Mapped[str] = mapped_column(String(60), nullable=False, index=True)
code: Mapped[str] = mapped_column(String(64), nullable=False)
label: Mapped[str] = mapped_column(String(255), nullable=False)
# Dependencia (Estado→País, Municipio→Estado, …)
parent_catalog: Mapped[str | None] = mapped_column(String(60), nullable=True)
parent_code: Mapped[str | None] = mapped_column(String(64), nullable=True)
# NULL = global (Aduanasoft); con valor = catálogo propio del tenant (cliente).
tenant_id: Mapped[int | None] = mapped_column(Integer, nullable=True, index=True)
sort_order: Mapped[int] = mapped_column(Integer, nullable=False, server_default=text("0"))
is_active: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("true"))
# Catálogos base SAT/ISO: no se pueden borrar (solo activar/desactivar).
is_system: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
extra: Mapped[dict | None] = mapped_column(JSON, nullable=True)
created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False, server_default=func.now())
updated_at: Mapped[datetime] = mapped_column(
DateTime, nullable=False, server_default=func.now(), onupdate=func.now()
)

80
backend/api/v1/modules/crm/catalogs/routes.py
View File

@@ -1,6 +1,10 @@
"""Endpoints de catálogos de referencia y participantes del proceso (R-T-01, R-T-10)."""
"""Endpoints de catálogos de referencia y participantes del proceso (R-T-01, R-T-10).
from fastapi import APIRouter, Depends, Query
Incluye el CRUD de catálogos de referencia (T2026-07-081/082): SAT/ISO globales
(Aduanasoft) y catálogos propios de cada cliente (tenant).
"""
from fastapi import APIRouter, Depends, Query, status
from sqlalchemy.orm import Session
from core.database import get_core_db
@@ -8,7 +12,9 @@ from core.security import get_current_user
from ..accounts.models import Account
from ..suppliers.models import Supplier
from . import service as catalog_service
from .data import INCOTERMS, PARTICIPANT_ROLES
from .dto import CatalogItemCreate, CatalogItemResponse, CatalogItemUpdate, CatalogMeta
router = APIRouter()
@@ -31,6 +37,76 @@ def list_participant_roles(
return PARTICIPANT_ROLES
# ----------------------------------------------------------------------------
# Catálogos de referencia (CRUD) — T2026-07-081/082
# ----------------------------------------------------------------------------
@router.get("/catalogs", response_model=list[CatalogMeta])
def list_catalog_meta(
company_id: int = Query(..., description="Company ID"),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Lista los catálogos disponibles (global + del tenant) con su conteo."""
return catalog_service.list_meta(db, current_user["tenant_id"])
@router.get("/catalogs/{catalog}", response_model=list[CatalogItemResponse])
def list_catalog_items(
catalog: str,
company_id: int = Query(..., description="Company ID"),
parent_code: str | None = Query(None, description="Filtra dependientes (ej. Estado por País)"),
include_inactive: bool = Query(False),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Opciones de un catálogo (global + del tenant), activas y ordenadas."""
return catalog_service.list_items(
db, catalog, current_user["tenant_id"], parent_code=parent_code, include_inactive=include_inactive
)
@router.post(
"/catalogs/{catalog}", response_model=CatalogItemResponse, status_code=status.HTTP_201_CREATED
)
def create_catalog_item(
catalog: str,
data: CatalogItemCreate,
company_id: int = Query(..., description="Company ID"),
scope: str | None = Query("tenant", description="'tenant' (cliente) o 'global' (Aduanasoft, hub_admin)"),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Inserta una opción en un catálogo."""
return catalog_service.create_item(db, catalog, data, current_user, scope=scope)
@router.patch("/catalogs/{catalog}/{item_id}", response_model=CatalogItemResponse)
def update_catalog_item(
catalog: str,
item_id: int,
data: CatalogItemUpdate,
company_id: int = Query(..., description="Company ID"),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Edita una opción de catálogo."""
return catalog_service.update_item(db, catalog, item_id, data, current_user)
@router.delete("/catalogs/{catalog}/{item_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_catalog_item(
catalog: str,
item_id: int,
company_id: int = Query(..., description="Company ID"),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Borra una opción de catálogo (los catálogos base del sistema no se borran)."""
catalog_service.delete_item(db, catalog, item_id, current_user)
@router.get("/participants")
def list_participants(
company_id: int = Query(..., description="Company ID"),

69
backend/api/v1/modules/crm/catalogs/seed.py Normal file
View File

@@ -0,0 +1,69 @@
"""Siembra de catálogos globales (Aduanasoft) del CRM.
Idempotente: inserta solo las claves que aún no existen (tenant_id NULL). Se
puede correr múltiples veces sin duplicar. Para ejecutarlo en un entorno:
docker compose exec backend python -m api.v1.modules.crm.catalogs.seed
"""
import logging
from sqlalchemy.orm import Session
from .models import CatalogItem
from .seed_data import GLOBAL_CATALOGS
logger = logging.getLogger(__name__)
def seed_global_catalogs(db: Session) -> dict:
"""Inserta los catálogos globales que falten. Devuelve un resumen {catalog: nuevos}."""
summary: dict[str, int] = {}
for catalog, meta in GLOBAL_CATALOGS.items():
is_system = bool(meta.get("is_system", False))
existing = {
row.code
for row in db.query(CatalogItem.code).filter(
CatalogItem.catalog == catalog, CatalogItem.tenant_id.is_(None)
)
}
added = 0
for order, item in enumerate(meta["items"]):
if item["code"] in existing:
continue
db.add(
CatalogItem(
catalog=catalog,
code=item["code"],
label=item["label"],
parent_catalog=item.get("parent_catalog"),
parent_code=item.get("parent_code"),
extra=item.get("extra"),
tenant_id=None,
sort_order=order,
is_active=True,
is_system=is_system,
)
)
added += 1
if added:
summary[catalog] = added
db.commit()
total = sum(summary.values())
logger.info("seed_global_catalogs: %s nuevas filas en %s catálogos", total, len(summary))
return summary
def _run() -> None:
from core.database import CoreSessionLocal
db = CoreSessionLocal()
try:
result = seed_global_catalogs(db)
print("Catálogos sembrados (nuevos):", result or "0 (ya estaban todos)")
finally:
db.close()
if __name__ == "__main__":
_run()

874
backend/api/v1/modules/crm/catalogs/seed_data.py Normal file
View File

@@ -0,0 +1,874 @@
"""Datos semilla de los catálogos de referencia del CRM.
SAT/ISO + estándar + Medidas de Equipos (tipo_equipo con dimensiones en extra)
+ catálogos del módulo Tarifario. Globales con tenant_id NULL.
"""
GLOBAL_CATALOGS = {'tipo_registro': {'label': 'Tipo de registro',
'is_system': True,
'items': [{'code': 'cliente', 'label': 'Cliente'}, {'code': 'prospecto', 'label': 'Prospecto'}]},
'tipo_persona': {'label': 'Tipo de persona',
'is_system': True,
'items': [{'code': 'fisica', 'label': 'Persona física'},
{'code': 'moral', 'label': 'Persona moral'}]},
'estatus': {'label': 'Estatus',
'is_system': True,
'items': [{'code': 'active', 'label': 'Activo'}, {'code': 'inactive', 'label': 'Inactivo'}]},
'giro': {'label': 'Giro o industria',
'is_system': False,
'items': [{'code': 'importadora', 'label': 'Importadora'},
{'code': 'exportadora', 'label': 'Exportadora'},
{'code': 'manufactura', 'label': 'Manufactura'},
{'code': 'comercializadora', 'label': 'Comercializadora'},
{'code': 'logistica', 'label': 'Logística y transporte'},
{'code': 'agencia_aduanal', 'label': 'Agencia aduanal'},
{'code': 'maquiladora', 'label': 'Maquiladora / IMMEX'},
{'code': 'servicios', 'label': 'Servicios'},
{'code': 'otro', 'label': 'Otro'}]},
'clasificacion_cliente': {'label': 'Clasificación del cliente',
'is_system': False,
'items': [{'code': 'importador', 'label': 'Importador'},
{'code': 'exportador', 'label': 'Exportador'},
{'code': 'importador_exportador', 'label': 'Importador/Exportador'}]},
'medio_contacto': {'label': 'Medio de contacto preferido',
'is_system': False,
'items': [{'code': 'llamada', 'label': 'Llamada telefónica'},
{'code': 'correo', 'label': 'Correo electrónico'},
{'code': 'videoconferencia', 'label': 'Videoconferencia'},
{'code': 'whatsapp', 'label': 'WhatsApp'},
{'code': 'otro', 'label': 'Otro'}]},
'idioma': {'label': 'Idioma',
'is_system': False,
'items': [{'code': 'es', 'label': 'Español'},
{'code': 'en', 'label': 'Inglés'},
{'code': 'zh', 'label': 'Chino (mandarín)'},
{'code': 'pt', 'label': 'Portugués'},
{'code': 'fr', 'label': 'Francés'},
{'code': 'de', 'label': 'Alemán'},
{'code': 'ja', 'label': 'Japonés'},
{'code': 'ko', 'label': 'Coreano'},
{'code': 'it', 'label': 'Italiano'},
{'code': 'otro', 'label': 'Otro'}]},
'regimen_fiscal': {'label': 'Régimen fiscal',
'is_system': False,
'items': [{'code': 'fisica', 'label': 'Persona física'},
{'code': 'moral', 'label': 'Persona moral'}]},
'uso_cfdi': {'label': 'Uso de CFDI (SAT)',
'is_system': True,
'items': [{'code': 'G01', 'label': 'Adquisición de mercancías'},
{'code': 'G02', 'label': 'Devoluciones, descuentos o bonificaciones'},
{'code': 'G03', 'label': 'Gastos en general'},
{'code': 'I01', 'label': 'Construcciones'},
{'code': 'I02', 'label': 'Mobiliario y equipo de oficina por inversiones'},
{'code': 'I03', 'label': 'Equipo de transporte'},
{'code': 'I04', 'label': 'Equipo de cómputo y accesorios'},
{'code': 'I05', 'label': 'Dados, troqueles, moldes, matrices y herramental'},
{'code': 'I06', 'label': 'Comunicaciones telefónicas'},
{'code': 'I07', 'label': 'Comunicaciones satelitales'},
{'code': 'I08', 'label': 'Otra maquinaria y equipo'},
{'code': 'D01', 'label': 'Honorarios médicos, dentales y gastos hospitalarios'},
{'code': 'D02', 'label': 'Gastos médicos por incapacidad o discapacidad'},
{'code': 'D03', 'label': 'Gastos funerales'},
{'code': 'D04', 'label': 'Donativos'},
{'code': 'D05', 'label': 'Intereses por créditos hipotecarios'},
{'code': 'D06', 'label': 'Aportaciones voluntarias al SAR'},
{'code': 'D07', 'label': 'Primas por seguros de gastos médicos'},
{'code': 'D08', 'label': 'Gastos de transportación escolar obligatoria'},
{'code': 'D09', 'label': 'Depósitos en cuentas para el ahorro'},
{'code': 'D10', 'label': 'Pagos por servicios educativos (colegiaturas)'},
{'code': 'S01', 'label': 'Sin efectos fiscales'},
{'code': 'CP01', 'label': 'Pagos'},
{'code': 'CN01', 'label': 'Nómina'},
{'code': 'P01', 'label': 'Por definir'}]},
'forma_pago': {'label': 'Forma de pago (SAT)',
'is_system': True,
'items': [{'code': '1', 'label': 'Efectivo'},
{'code': '2', 'label': 'Cheque nominativo'},
{'code': '3', 'label': 'Transferencia electrónica de fondos'},
{'code': '4', 'label': 'Tarjeta de crédito'},
{'code': '5', 'label': 'Monedero electrónico'},
{'code': '6', 'label': 'Dinero electrónico'},
{'code': '8', 'label': 'Vales de despensa'},
{'code': '12', 'label': 'Dación en pago'},
{'code': '13', 'label': 'Pago por subrogación'},
{'code': '14', 'label': 'Pago por consignación'},
{'code': '15', 'label': 'Condonación'},
{'code': '17', 'label': 'Compensación'},
{'code': '23', 'label': 'Novación'},
{'code': '24', 'label': 'Confusión'},
{'code': '25', 'label': 'Remisión de deuda'},
{'code': '26', 'label': 'Prescripción o caducidad'},
{'code': '27', 'label': 'A satisfacción del acreedor'},
{'code': '28', 'label': 'Tarjeta de débito'},
{'code': '29', 'label': 'Tarjeta de servicios'},
{'code': '30', 'label': 'Aplicación de anticipos'},
{'code': '31', 'label': 'Intermediario pagos'},
{'code': '99', 'label': 'Por definir'}]},
'metodo_pago': {'label': 'Método de pago (SAT)',
'is_system': True,
'items': [{'code': 'PPD', 'label': 'Pago en parcialidades o diferido'},
{'code': 'PUE', 'label': 'Pago en una sola exhibición'}]},
'moneda': {'label': 'Moneda (ISO 4217)',
'is_system': True,
'items': [{'code': 'CRC', 'label': 'Colón costarricense'},
{'code': 'CUC', 'label': 'Peso Convertible'},
{'code': 'CUP', 'label': 'Peso Cubano'},
{'code': 'CVE', 'label': 'Cabo Verde Escudo'},
{'code': 'CZK', 'label': 'Corona checa'},
{'code': 'DJF', 'label': 'Franco de Djibouti'},
{'code': 'DKK', 'label': 'Corona danesa'},
{'code': 'DOP', 'label': 'Peso Dominicano'},
{'code': 'DZD', 'label': 'Dinar argelino'},
{'code': 'EGP', 'label': 'Libra egipcia'},
{'code': 'ERN', 'label': 'Nakfa'},
{'code': 'ETB', 'label': 'Birr etíope'},
{'code': 'EUR', 'label': 'Euro'},
{'code': 'FJD', 'label': 'Dólar de Fiji'},
{'code': 'FKP', 'label': 'Libra malvinense'},
{'code': 'GBP', 'label': 'Libra Esterlina'},
{'code': 'GEL', 'label': 'Lari'},
{'code': 'GHS', 'label': 'Cedi de Ghana'},
{'code': 'GIP', 'label': 'Libra de Gibraltar'},
{'code': 'GMD', 'label': 'Dalasi'},
{'code': 'GNF', 'label': 'Franco guineano'},
{'code': 'GTQ', 'label': 'Quetzal'},
{'code': 'GYD', 'label': 'Dólar guyanés'},
{'code': 'HKD', 'label': 'Dolar De Hong Kong'},
{'code': 'HNL', 'label': 'Lempira'},
{'code': 'HRK', 'label': 'Kuna'},
{'code': 'HTG', 'label': 'Gourde'},
{'code': 'HUF', 'label': 'Florín'},
{'code': 'IDR', 'label': 'Rupia'},
{'code': 'ILS', 'label': 'Nuevo Shekel Israelí'},
{'code': 'INR', 'label': 'Rupia india'},
{'code': 'IQD', 'label': 'Dinar iraquí'},
{'code': 'IRR', 'label': 'Rial iraní'},
{'code': 'ISK', 'label': 'Corona islandesa'},
{'code': 'JMD', 'label': 'Dólar Jamaiquino'},
{'code': 'JOD', 'label': 'Dinar jordano'},
{'code': 'JPY', 'label': 'Yen'},
{'code': 'KES', 'label': 'Chelín keniano'},
{'code': 'KGS', 'label': 'Som'},
{'code': 'KHR', 'label': 'Riel'},
{'code': 'KMF', 'label': 'Franco Comoro'},
{'code': 'KPW', 'label': 'Corea del Norte ganó'},
{'code': 'KRW', 'label': 'Won'},
{'code': 'KWD', 'label': 'Dinar kuwaití'},
{'code': 'KYD', 'label': 'Dólar de las Islas Caimán'},
{'code': 'KZT', 'label': 'Tenge'},
{'code': 'LAK', 'label': 'Kip'},
{'code': 'LBP', 'label': 'Libra libanesa'},
{'code': 'LKR', 'label': 'Rupia de Sri Lanka'},
{'code': 'LRD', 'label': 'Dólar liberiano'},
{'code': 'LSL', 'label': 'Loti'},
{'code': 'LYD', 'label': 'Dinar libio'},
{'code': 'MAD', 'label': 'Dirham marroquí'},
{'code': 'MDL', 'label': 'Leu moldavo'},
{'code': 'MGA', 'label': 'Ariary malgache'},
{'code': 'MKD', 'label': 'Denar'},
{'code': 'MMK', 'label': 'Kyat'},
{'code': 'MNT', 'label': 'Tugrik'},
{'code': 'MOP', 'label': 'Pataca'},
{'code': 'MRO', 'label': 'Ouguiya'},
{'code': 'MUR', 'label': 'Rupia de Mauricio'},
{'code': 'MVR', 'label': 'Rupia'},
{'code': 'MWK', 'label': 'Kwacha'},
{'code': 'MXN', 'label': 'Peso Mexicano'},
{'code': 'MXV', 'label': 'México Unidad de Inversión (UDI)'},
{'code': 'MYR', 'label': 'Ringgit malayo'},
{'code': 'MZN', 'label': 'Mozambique Metical'},
{'code': 'NAD', 'label': 'Dólar de Namibia'},
{'code': 'NGN', 'label': 'Naira'},
{'code': 'NIO', 'label': 'Córdoba Oro'},
{'code': 'NOK', 'label': 'Corona noruega'},
{'code': 'NPR', 'label': 'Rupia nepalí'},
{'code': 'NZD', 'label': 'Dólar de Nueva Zelanda'},
{'code': 'OMR', 'label': 'Rial omaní'},
{'code': 'PAB', 'label': 'Balboa'},
{'code': 'PEN', 'label': 'Nuevo Sol'},
{'code': 'PGK', 'label': 'Kina'},
{'code': 'PHP', 'label': 'Peso filipino'},
{'code': 'PKR', 'label': 'Rupia de Pakistán'},
{'code': 'PLN', 'label': 'Zloty'},
{'code': 'PYG', 'label': 'Guaraní'},
{'code': 'QAR', 'label': 'Qatar Rial'},
{'code': 'RON', 'label': 'Leu rumano'},
{'code': 'RSD', 'label': 'Dinar serbio'},
{'code': 'RUB', 'label': 'Rublo ruso'},
{'code': 'RWF', 'label': 'Franco ruandés'},
{'code': 'SAR', 'label': 'Riyal saudí'},
{'code': 'SBD', 'label': 'Dólar de las Islas Salomón'},
{'code': 'SCR', 'label': 'Rupia de Seychelles'},
{'code': 'SDG', 'label': 'Libra sudanesa'},
{'code': 'SEK', 'label': 'Corona sueca'},
{'code': 'SGD', 'label': 'Dolar De Singapur'},
{'code': 'SHP', 'label': 'Libra de Santa Helena'},
{'code': 'SLL', 'label': 'Leona'},
{'code': 'SOS', 'label': 'Chelín somalí'},
{'code': 'SRD', 'label': 'Dólar de Suriname'},
{'code': 'SSP', 'label': 'Libra sudanesa Sur'},
{'code': 'STD', 'label': 'Dobra'},
{'code': 'SVC', 'label': 'Colon El Salvador'},
{'code': 'SYP', 'label': 'Libra Siria'},
{'code': 'SZL', 'label': 'Lilangeni'},
{'code': 'THB', 'label': 'Baht'},
{'code': 'TJS', 'label': 'Somoni'},
{'code': 'TMT', 'label': 'Turkmenistán nuevo manat'},
{'code': 'TND', 'label': 'Dinar tunecino'},
{'code': 'TOP', 'label': "Pa'anga"},
{'code': 'TRY', 'label': 'Lira turca'},
{'code': 'TTD', 'label': 'Dólar de Trinidad y Tobago'},
{'code': 'TWD', 'label': 'Nuevo dólar de Taiwán'},
{'code': 'TZS', 'label': 'Shilling tanzano'},
{'code': 'UAH', 'label': 'Hryvnia'},
{'code': 'UGX', 'label': 'Shilling de Uganda'},
{'code': 'USD', 'label': 'Dolar americano'},
{'code': 'USN', 'label': 'Dólar estadounidense (día siguiente)'},
{'code': 'UYI', 'label': 'Peso Uruguay en Unidades Indexadas (URUIURUI)'},
{'code': 'UYU', 'label': 'Peso Uruguayo'},
{'code': 'UZS', 'label': 'Uzbekistán Sum'},
{'code': 'VEF', 'label': 'Bolívar'},
{'code': 'VND', 'label': 'Dong'},
{'code': 'VUV', 'label': 'Vatu'},
{'code': 'WST', 'label': 'Tala'},
{'code': 'XAF', 'label': 'Franco CFA BEAC'},
{'code': 'XAG', 'label': 'Plata'},
{'code': 'XAU', 'label': 'Oro'},
{'code': 'XBA', 'label': 'Unidad de Mercados de Bonos Unidad Europea Composite (EURCO)'},
{'code': 'XBB', 'label': 'Unidad Monetaria de Bonos de Mercados Unidad Europea (UEM-6)'},
{'code': 'XBC', 'label': 'Mercados de Bonos Unidad Europea unidad de cuenta a 9 (UCE-9)'},
{'code': 'XBD', 'label': 'Mercados de Bonos Unidad Europea unidad de cuenta a 17 (UCE-17)'},
{'code': 'XCD', 'label': 'Dólar del Caribe Oriental'},
{'code': 'XDR', 'label': 'DEG (Derechos Especiales de Giro)'},
{'code': 'XOF', 'label': 'Franco CFA BCEAO'},
{'code': 'XPD', 'label': 'Paladio'},
{'code': 'XPF', 'label': 'Franco CFP'},
{'code': 'XPT', 'label': 'Platino'},
{'code': 'XSU', 'label': 'Sucre'},
{'code': 'XTS', 'label': 'Códigos reservados específicamente para propósitos de prueba'},
{'code': 'XUA', 'label': 'Unidad ADB de Cuenta'},
{'code': 'XXX',
'label': 'Los códigos asignados para las transacciones en que intervenga ninguna moneda'},
{'code': 'YER', 'label': 'Rial yemení'},
{'code': 'ZAR', 'label': 'Rand'},
{'code': 'ZMW', 'label': 'Kwacha zambiano'},
{'code': 'ZWL', 'label': 'Zimbabwe Dólar'},
{'code': 'NULL', 'label': 'NULL'}]},
'pais': {'label': 'País (ISO 3166)',
'is_system': True,
'items': [{'code': 'ABW', 'label': 'Aruba'},
{'code': 'AFG', 'label': 'Afganistán'},
{'code': 'AGO', 'label': 'Angola'},
{'code': 'AIA', 'label': 'Anguila'},
{'code': 'ALA', 'label': 'Islas Åland'},
{'code': 'ALB', 'label': 'Albania'},
{'code': 'AND', 'label': 'Andorra'},
{'code': 'ARE', 'label': 'Emiratos Árabes Unidos (Los)'},
{'code': 'ARG', 'label': 'Argentina'},
{'code': 'ARM', 'label': 'Armenia'},
{'code': 'ASM', 'label': 'Samoa Americana'},
{'code': 'ATA', 'label': 'Antártida'},
{'code': 'ATF', 'label': 'Territorios Australes Franceses (los)'},
{'code': 'ATG', 'label': 'Antigua y Barbuda'},
{'code': 'AUS', 'label': 'Australia'},
{'code': 'AUT', 'label': 'Austria'},
{'code': 'AZE', 'label': 'Azerbaiyán'},
{'code': 'BDI', 'label': 'Burundi'},
{'code': 'BEL', 'label': 'Bélgica'},
{'code': 'BEN', 'label': 'Benín'},
{'code': 'BES', 'label': 'Bonaire, San Eustaquio y Saba'},
{'code': 'BFA', 'label': 'Burkina Faso'},
{'code': 'BGD', 'label': 'Bangladés'},
{'code': 'BGR', 'label': 'Bulgaria'},
{'code': 'BHR', 'label': 'Baréin'},
{'code': 'BHS', 'label': 'Bahamas (las)'},
{'code': 'BIH', 'label': 'Bosnia y Herzegovina'},
{'code': 'BLM', 'label': 'San Bartolomé'},
{'code': 'BLR', 'label': 'Bielorrusia'},
{'code': 'BLZ', 'label': 'Belice'},
{'code': 'BMU', 'label': 'Bermudas'},
{'code': 'BOL', 'label': 'Bolivia, Estado Plurinacional de'},
{'code': 'BRA', 'label': 'Brasil'},
{'code': 'BRB', 'label': 'Barbados'},
{'code': 'BRN', 'label': 'Brunéi Darussalam'},
{'code': 'BTN', 'label': 'Bután'},
{'code': 'BVT', 'label': 'Isla Bouvet'},
{'code': 'BWA', 'label': 'Botsuana'},
{'code': 'CAF', 'label': 'República Centroafricana (la)'},
{'code': 'CAN', 'label': 'Canadá'},
{'code': 'CCK', 'label': 'Islas Cocos (Keeling)'},
{'code': 'CHE', 'label': 'Suiza'},
{'code': 'CHL', 'label': 'Chile'},
{'code': 'CHN', 'label': 'China'},
{'code': 'CIV', 'label': "Côte d'Ivoire"},
{'code': 'CMR', 'label': 'Camerún'},
{'code': 'COD', 'label': 'Congo (la República Democrática del)'},
{'code': 'COG', 'label': 'Congo'},
{'code': 'COK', 'label': 'Islas Cook (las)'},
{'code': 'COL', 'label': 'Colombia'},
{'code': 'COM', 'label': 'Comoras'},
{'code': 'CPV', 'label': 'Cabo Verde'},
{'code': 'CRI', 'label': 'Costa Rica'},
{'code': 'CUB', 'label': 'Cuba'},
{'code': 'CUW', 'label': 'Curaçao'},
{'code': 'CXR', 'label': 'Isla de Navidad'},
{'code': 'CYM', 'label': 'Islas Caimán (las)'},
{'code': 'CYP', 'label': 'Chipre'},
{'code': 'CZE', 'label': 'República Checa (la)'},
{'code': 'DEU', 'label': 'Alemania'},
{'code': 'DJI', 'label': 'Yibuti'},
{'code': 'DMA', 'label': 'Dominica'},
{'code': 'DNK', 'label': 'Dinamarca'},
{'code': 'DOM', 'label': 'República Dominicana (la)'},
{'code': 'DZA', 'label': 'Argelia'},
{'code': 'ECU', 'label': 'Ecuador'},
{'code': 'EGY', 'label': 'Egipto'},
{'code': 'ERI', 'label': 'Eritrea'},
{'code': 'ESH', 'label': 'Sahara Occidental'},
{'code': 'ESP', 'label': 'España'},
{'code': 'EST', 'label': 'Estonia'},
{'code': 'ETH', 'label': 'Etiopía'},
{'code': 'FIN', 'label': 'Finlandia'},
{'code': 'FJI', 'label': 'Fiyi'},
{'code': 'FLK', 'label': 'Islas Malvinas [Falkland] (las)'},
{'code': 'FRA', 'label': 'Francia'},
{'code': 'FRO', 'label': 'Islas Feroe (las)'},
{'code': 'FSM', 'label': 'Micronesia (los Estados Federados de)'},
{'code': 'GAB', 'label': 'Gabón'},
{'code': 'GBR', 'label': 'Reino Unido (el)'},
{'code': 'GEO', 'label': 'Georgia'},
{'code': 'GGY', 'label': 'Guernsey'},
{'code': 'GHA', 'label': 'Ghana'},
{'code': 'GIB', 'label': 'Gibraltar'},
{'code': 'GIN', 'label': 'Guinea'},
{'code': 'GLP', 'label': 'Guadalupe'},
{'code': 'GMB', 'label': 'Gambia (La)'},
{'code': 'GNB', 'label': 'Guinea-Bisáu'},
{'code': 'GNQ', 'label': 'Guinea Ecuatorial'},
{'code': 'GRC', 'label': 'Grecia'},
{'code': 'GRD', 'label': 'Granada'},
{'code': 'GRL', 'label': 'Groenlandia'},
{'code': 'GTM', 'label': 'Guatemala'},
{'code': 'GUF', 'label': 'Guayana Francesa'},
{'code': 'GUM', 'label': 'Guam'},
{'code': 'GUY', 'label': 'Guyana'},
{'code': 'HKG', 'label': 'Hong Kong'},
{'code': 'HMD', 'label': 'Isla Heard e Islas McDonald'},
{'code': 'HND', 'label': 'Honduras'},
{'code': 'HRV', 'label': 'Croacia'},
{'code': 'HTI', 'label': 'Haití'},
{'code': 'HUN', 'label': 'Hungría'},
{'code': 'IDN', 'label': 'Indonesia'},
{'code': 'IMN', 'label': 'Isla de Man'},
{'code': 'IND', 'label': 'India'},
{'code': 'IOT', 'label': 'Territorio Británico del Océano Índico (el)'},
{'code': 'IRL', 'label': 'Irlanda'},
{'code': 'IRN', 'label': 'Irán (la República Islámica de)'},
{'code': 'IRQ', 'label': 'Irak'},
{'code': 'ISL', 'label': 'Islandia'},
{'code': 'ISR', 'label': 'Israel'},
{'code': 'ITA', 'label': 'Italia'},
{'code': 'JAM', 'label': 'Jamaica'},
{'code': 'JEY', 'label': 'Jersey'},
{'code': 'JOR', 'label': 'Jordania'},
{'code': 'JPN', 'label': 'Japón'},
{'code': 'KAZ', 'label': 'Kazajistán'},
{'code': 'KEN', 'label': 'Kenia'},
{'code': 'KGZ', 'label': 'Kirguistán'},
{'code': 'KHM', 'label': 'Camboya'},
{'code': 'KIR', 'label': 'Kiribati'},
{'code': 'KNA', 'label': 'San Cristóbal y Nieves'},
{'code': 'KOR', 'label': 'Corea (la República de)'},
{'code': 'KWT', 'label': 'Kuwait'},
{'code': 'LAO', 'label': 'Lao, (la) República Democrática Popular'},
{'code': 'LBN', 'label': 'Líbano'},
{'code': 'LBR', 'label': 'Liberia'},
{'code': 'LBY', 'label': 'Libia'},
{'code': 'LCA', 'label': 'Santa Lucía'},
{'code': 'LIE', 'label': 'Liechtenstein'},
{'code': 'LKA', 'label': 'Sri Lanka'},
{'code': 'LSO', 'label': 'Lesoto'},
{'code': 'LTU', 'label': 'Lituania'},
{'code': 'LUX', 'label': 'Luxemburgo'},
{'code': 'LVA', 'label': 'Letonia'},
{'code': 'MAC', 'label': 'Macao'},
{'code': 'MAF', 'label': 'San Martín (parte francesa)'},
{'code': 'MAR', 'label': 'Marruecos'},
{'code': 'MCO', 'label': 'Mónaco'},
{'code': 'MDA', 'label': 'Moldavia (la República de)'},
{'code': 'MDG', 'label': 'Madagascar'},
{'code': 'MDV', 'label': 'Maldivas'},
{'code': 'MEX', 'label': 'México'},
{'code': 'MHL', 'label': 'Islas Marshall (las)'},
{'code': 'MKD', 'label': 'Macedonia (la antigua República Yugoslava de)'},
{'code': 'MLI', 'label': 'Malí'},
{'code': 'MLT', 'label': 'Malta'},
{'code': 'MMR', 'label': 'Myanmar'},
{'code': 'MNE', 'label': 'Montenegro'},
{'code': 'MNG', 'label': 'Mongolia'},
{'code': 'MNP', 'label': 'Islas Marianas del Norte (las)'},
{'code': 'MOZ', 'label': 'Mozambique'},
{'code': 'MRT', 'label': 'Mauritania'},
{'code': 'MSR', 'label': 'Montserrat'},
{'code': 'MTQ', 'label': 'Martinica'},
{'code': 'MUS', 'label': 'Mauricio'},
{'code': 'MWI', 'label': 'Malaui'},
{'code': 'MYS', 'label': 'Malasia'},
{'code': 'MYT', 'label': 'Mayotte'},
{'code': 'NAM', 'label': 'Namibia'},
{'code': 'NCL', 'label': 'Nueva Caledonia'},
{'code': 'NER', 'label': 'Níger (el)'},
{'code': 'NFK', 'label': 'Isla Norfolk'},
{'code': 'NGA', 'label': 'Nigeria'},
{'code': 'NIC', 'label': 'Nicaragua'},
{'code': 'NIU', 'label': 'Niue'},
{'code': 'NLD', 'label': 'Países Bajos (los)'},
{'code': 'NOR', 'label': 'Noruega'},
{'code': 'NPL', 'label': 'Nepal'},
{'code': 'NRU', 'label': 'Nauru'},
{'code': 'NZL', 'label': 'Nueva Zelanda'},
{'code': 'OMN', 'label': 'Omán'},
{'code': 'PAK', 'label': 'Pakistán'},
{'code': 'PAN', 'label': 'Panamá'},
{'code': 'PCN', 'label': 'Pitcairn'},
{'code': 'PER', 'label': 'Perú'},
{'code': 'PHL', 'label': 'Filipinas (las)'},
{'code': 'PLW', 'label': 'Palaos'},
{'code': 'PNG', 'label': 'Papúa Nueva Guinea'},
{'code': 'POL', 'label': 'Polonia'},
{'code': 'PRI', 'label': 'Puerto Rico'},
{'code': 'PRK', 'label': 'Corea (la República Democrática Popular de)'},
{'code': 'PRT', 'label': 'Portugal'},
{'code': 'PRY', 'label': 'Paraguay'},
{'code': 'PSE', 'label': 'Palestina, Estado de'},
{'code': 'PYF', 'label': 'Polinesia Francesa'},
{'code': 'QAT', 'label': 'Catar'},
{'code': 'REU', 'label': 'Reunión'},
{'code': 'ROU', 'label': 'Rumania'},
{'code': 'RUS', 'label': 'Rusia, (la) Federación de'},
{'code': 'RWA', 'label': 'Ruanda'},
{'code': 'SAU', 'label': 'Arabia Saudita'},
{'code': 'SDN', 'label': 'Sudán (el)'},
{'code': 'SEN', 'label': 'Senegal'},
{'code': 'SGP', 'label': 'Singapur'},
{'code': 'SGS', 'label': 'Georgia del sur y las islas sandwich del sur'},
{'code': 'SHN', 'label': 'Santa Helena, Ascensión y Tristán de Acuña'},
{'code': 'SJM', 'label': 'Svalbard y Jan Mayen'},
{'code': 'SLB', 'label': 'Islas Salomón (las)'},
{'code': 'SLE', 'label': 'Sierra leona'},
{'code': 'NULL', 'label': 'NULL'}]},
'estado': {'label': 'Estado / Provincia',
'is_system': True,
'items': [{'code': 'AGU', 'label': 'Aguascalientes', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'BCN', 'label': 'Baja California', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'BCS', 'label': 'Baja California Sur', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'CAM', 'label': 'Campeche', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'CHP', 'label': 'Chiapas', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'CHH', 'label': 'Chihuahua', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'CMX', 'label': 'Ciudad de México', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'COA', 'label': 'Coahuila', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'COL', 'label': 'Colima', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'DUR', 'label': 'Durango', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'GUA', 'label': 'Guanajuato', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'GRO', 'label': 'Guerrero', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'HID', 'label': 'Hidalgo', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'JAL', 'label': 'Jalisco', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'MEX', 'label': 'Estado de México', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'MIC', 'label': 'Michoacán', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'MOR', 'label': 'Morelos', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'NAY', 'label': 'Nayarit', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'NLE', 'label': 'Nuevo León', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'OAX', 'label': 'Oaxaca', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'PUE', 'label': 'Puebla', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'QUE', 'label': 'Querétaro', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'ROO', 'label': 'Quintana Roo', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'SLP', 'label': 'San Luis Potosí', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'SIN', 'label': 'Sinaloa', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'SON', 'label': 'Sonora', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'TAB', 'label': 'Tabasco', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'TAM', 'label': 'Tamaulipas', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'TLA', 'label': 'Tlaxcala', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'VER', 'label': 'Veracruz', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'YUC', 'label': 'Yucatán', 'parent_catalog': 'pais', 'parent_code': 'MEX'},
{'code': 'ZAC', 'label': 'Zacatecas', 'parent_catalog': 'pais', 'parent_code': 'MEX'}]},
'tipo_domicilio': {'label': 'Tipo de domicilio',
'is_system': False,
'items': [{'code': 'fiscal', 'label': 'Fiscal'},
{'code': 'oficina', 'label': 'Oficina'},
{'code': 'sucursal', 'label': 'Sucursal'},
{'code': 'bodega', 'label': 'Bodega'},
{'code': 'patio', 'label': 'Patio'},
{'code': 'terminal', 'label': 'Terminal'},
{'code': 'almacen', 'label': 'Almacén'}]},
'area': {'label': 'Área / Departamento',
'is_system': False,
'items': [{'code': 'ventas', 'label': 'Ventas'},
{'code': 'operaciones', 'label': 'Operaciones'},
{'code': 'facturacion', 'label': 'Facturación'},
{'code': 'cobranza', 'label': 'Cobranza'},
{'code': 'servicio_cliente', 'label': 'Servicio al cliente'}]},
'cobertura': {'label': 'Cobertura',
'is_system': True,
'items': [{'code': 'nacional', 'label': 'Nacional'},
{'code': 'internacional', 'label': 'Internacional'}]},
'clasificacion_proveedor': {'label': 'Clasificación del proveedor',
'is_system': False,
'items': [{'code': 'naviera', 'label': 'Naviera'},
{'code': 'aerolinea', 'label': 'Aerolínea'},
{'code': 'transportista_terrestre', 'label': 'Transportista Terrestre'},
{'code': 'ferrocarril', 'label': 'Ferrocarril'},
{'code': 'agente_aduanal', 'label': 'Agente Aduanal'},
{'code': 'agente_carga', 'label': 'Agente de Carga'},
{'code': 'agente_corresponsal', 'label': 'Agente Corresponsal'},
{'code': 'almacen', 'label': 'Almacén'},
{'code': 'aseguradora', 'label': 'Aseguradora'},
{'code': 'paqueteria', 'label': 'Paquetería'},
{'code': 'otro', 'label': 'Otro'}]},
'tipo_equipo': {'label': 'Tipo de equipo / contenedor',
'is_system': True,
'items': [{'code': '40DC',
'label': "40' Standard",
'extra': {'modo': 'maritimo',
'largo_m': 12.035,
'ancho_m': 2.35,
'alto_m': 2.392,
'capacidad_m3': 67.7,
'tara_kg': 3700,
'carga_max_kg': 26790}},
{'code': '20DC',
'label': "20' Standard",
'extra': {'modo': 'maritimo',
'largo_m': 5.9,
'ancho_m': 2.35,
'alto_m': 2.392,
'capacidad_m3': 33.2,
'tara_kg': 2230,
'carga_max_kg': 21770}},
{'code': '20OT',
'label': "20' Open Top",
'extra': {'modo': 'maritimo',
'largo_m': 5.894,
'ancho_m': 2.311,
'alto_m': 2.354,
'capacidad_m3': 32.23,
'tara_kg': 2400,
'carga_max_kg': 30490}},
{'code': '20FR',
'label': "20' Flat Rack",
'extra': {'modo': 'maritimo',
'largo_m': 5.62,
'ancho_m': 2.23,
'alto_m': 2.233,
'tara_kg': 2530,
'carga_max_kg': 21470}},
{'code': '40HC',
'label': "40' High Cube",
'extra': {'modo': 'maritimo',
'largo_m': 12.036,
'ancho_m': 2.35,
'alto_m': 2.697,
'capacidad_m3': 76.3,
'tara_kg': 3970,
'carga_max_kg': 26510}},
{'code': '20PL',
'label': "20' Platform",
'extra': {'modo': 'maritimo',
'largo_m': 6.058,
'ancho_m': 2.438,
'alto_m': 0.37,
'tara_kg': 2520,
'carga_max_kg': 27960}},
{'code': '20FRC',
'label': "20' Flat Rack Collapsible",
'extra': {'modo': 'maritimo',
'largo_m': 5.618,
'ancho_m': 2.206,
'alto_m': 2.233,
'tara_kg': 2750,
'carga_max_kg': 27730}},
{'code': '20BK',
'label': "20' Bulk",
'extra': {'modo': 'maritimo',
'largo_m': 5.93,
'ancho_m': 2.35,
'alto_m': 2.34,
'capacidad_m3': 32.0,
'tara_kg': 2450,
'carga_max_kg': 21350}},
{'code': '20TK',
'label': "20' Tank",
'extra': {'modo': 'maritimo',
'largo_m': 6.058,
'ancho_m': 2.438,
'alto_m': 2.438,
'tara_kg': 4100,
'carga_max_kg': 26200}},
{'code': 'LD2',
'label': 'LD2',
'extra': {'modo': 'aereo',
'capacidad_m3': 3.5,
'tara_kg': 30,
'carga_max_kg': 1225,
'nota': 'Aviones 767'}},
{'code': 'LD3',
'label': 'LD3',
'extra': {'modo': 'aereo',
'capacidad_m3': 4.2,
'tara_kg': 80,
'carga_max_kg': 1587,
'nota': 'B747/B777/DC10/MD-11/A310/A330/A340'}},
{'code': 'LBD',
'label': 'LBD (Flex Door)',
'extra': {'modo': 'aereo',
'capacidad_m3': 7.0,
'tara_kg': 123,
'carga_max_kg': 2449,
'nota': 'Aviones 767'}},
{'code': 'LD6',
'label': 'LD6',
'extra': {'modo': 'aereo',
'capacidad_m3': 8.9,
'tara_kg': 175,
'carga_max_kg': 3175,
'nota': 'B747/B777/DC10/MD-11/A310/A330/A340'}},
{'code': 'PAG',
'label': 'PAP / PIP / PAG',
'extra': {'modo': 'aereo',
'capacidad_m3': 10.0,
'tara_kg': 120,
'carga_max_kg': 6033,
'nota': 'Boeing 747/767/777/DC10'}},
{'code': 'LD9',
'label': 'LD9 AAP',
'extra': {'modo': 'aereo',
'capacidad_m3': 10.0,
'tara_kg': 85,
'carga_max_kg': 1588,
'nota': 'Boeing 747/777/DC10'}},
{'code': 'XAW',
'label': 'XAW',
'extra': {'modo': 'aereo',
'capacidad_m3': 14.0,
'tara_kg': 170,
'carga_max_kg': 5000,
'nota': 'Boeing 747/777/DC10'}},
{'code': 'PMC',
'label': 'PMC',
'extra': {'modo': 'aereo',
'capacidad_m3': 12.7,
'tara_kg': 130,
'carga_max_kg': 6804,
'nota': 'Boeing 747/767/777'}},
{'code': 'LD8',
'label': 'LD8',
'extra': {'modo': 'aereo', 'capacidad_m3': 7.2, 'tara_kg': 120, 'carga_max_kg': 2450}},
{'code': 'DV48',
'label': "Dry Van 48'",
'extra': {'modo': 'terrestre',
'largo_m': 14.63,
'ancho_m': 2.59,
'alto_m': 2.3,
'capacidad_m3': 98.0,
'carga_max_kg': 20412,
'pallets': 22}},
{'code': 'SD',
'label': 'Legal Step Deck (Single Drop)',
'extra': {'modo': 'terrestre',
'largo_m': 11.58,
'ancho_m': 2.59,
'alto_m': 3.05,
'carga_max_kg': 20865}},
{'code': 'TANK',
'label': 'Tanker',
'extra': {'modo': 'terrestre',
'largo_m': 16.15,
'ancho_m': 2.59,
'alto_m': 2.3,
'capacidad_l': 22712}},
{'code': 'DV53',
'label': "Dry Van 53'",
'extra': {'modo': 'terrestre',
'largo_m': 16.15,
'ancho_m': 2.59,
'alto_m': 2.3,
'capacidad_m3': 99.11,
'carga_max_kg': 20412,
'pallets': 26}},
{'code': 'DD',
'label': 'Double Drop (Low Boy)',
'extra': {'modo': 'terrestre',
'largo_m': 8.53,
'ancho_m': 2.59,
'alto_m': 3.51,
'carga_max_kg': 18144}},
{'code': 'RF48',
'label': "48' Reefer Trailer",
'extra': {'modo': 'terrestre',
'largo_m': 14.63,
'ancho_m': 2.4,
'alto_m': 2.3,
'capacidad_m3': 90.0,
'carga_max_kg': 19958,
'pallets': 20}},
{'code': 'FB48',
'label': "48' Legal Flatbed",
'extra': {'modo': 'terrestre',
'largo_m': 14.63,
'ancho_m': 2.59,
'alto_m': 2.59,
'carga_max_kg': 21772}},
{'code': 'PUP28',
'label': "Pup Trailer 28'",
'extra': {'modo': 'terrestre',
'largo_m': 8.53,
'ancho_m': 2.59,
'alto_m': 2.3,
'capacidad_m3': 57.45,
'carga_max_kg': 9979,
'pallets': 14}},
{'code': 'IM53',
'label': "Intermodal 53' Container",
'extra': {'modo': 'terrestre',
'largo_m': 16.15,
'ancho_m': 2.59,
'alto_m': 2.3,
'capacidad_m3': 99.11,
'carga_max_kg': 19958,
'pallets': 24}}]},
'modo_tarifario': {'label': 'Modo de tarifario',
'is_system': True,
'items': [{'code': 'aereo', 'label': 'Aéreo'},
{'code': 'maritimo_fcl', 'label': 'Marítimo FCL'},
{'code': 'maritimo_lcl', 'label': 'Marítimo LCL'},
{'code': 'terrestre', 'label': 'Terrestre'}]},
'unidad_tarifa': {'label': 'Unidad de tarifa',
'is_system': True,
'items': [{'code': 'per_kg', 'label': 'Por kg'},
{'code': 'per_wm', 'label': 'Por peso/medida (W/M)'},
{'code': 'per_container', 'label': 'Por contenedor'},
{'code': 'flat', 'label': 'Tarifa plana'}]},
'concepto_cargo': {'label': 'Concepto de cargo',
'is_system': False,
'items': [{'code': 'combustible', 'label': 'Combustible (BAF/FSC)'},
{'code': 'dgr', 'label': 'Mercancía peligrosa (DGR)'},
{'code': 'moc', 'label': 'MOC (mínimo origen)'},
{'code': 'afs', 'label': 'AFS'},
{'code': 'thc', 'label': 'THC (manejo en terminal)'},
{'code': 'maniobras', 'label': 'Maniobras'},
{'code': 'almacenaje', 'label': 'Almacenaje'},
{'code': 'seguro', 'label': 'Seguro'},
{'code': 'despacho', 'label': 'Despacho aduanal'},
{'code': 'documentacion', 'label': 'Documentación'},
{'code': 'custodia', 'label': 'Custodia'},
{'code': 'otro', 'label': 'Otro'}]}}
TENANT_CATALOG_LABELS = {'servicio': 'Servicios que ofrece',
'puerto': 'Puertos donde opera',
'aeropuerto': 'Aeropuertos donde opera',
'aduana': 'Aduanas donde opera'}
# ---------------------------------------------------------------------------
# Catálogos del proceso comercial (Solicitud de servicio → Cotización).
# Alimentan los selects de la solicitud y del ciclo Oportunidad→Cotización.
# is_system = catálogos base que el cliente no puede borrar (sólo activar/desactivar).
# ---------------------------------------------------------------------------
GLOBAL_CATALOGS.update({
'tipo_operacion': {'label': 'Tipo de operación',
'is_system': True,
'items': [{'code': 'importacion', 'label': 'Importación'},
{'code': 'exportacion', 'label': 'Exportación'}]},
'medio_transporte': {'label': 'Medio de transporte',
'is_system': True,
'items': [{'code': 'maritimo', 'label': 'Marítimo'},
{'code': 'aereo', 'label': 'Aéreo'},
{'code': 'terrestre', 'label': 'Terrestre'},
{'code': 'ferroviario', 'label': 'Ferroviario'},
{'code': 'multimodal', 'label': 'Multimodal'}]},
'tipo_servicio': {'label': 'Tipo de servicio',
'is_system': True,
'items': [{'code': 'puerto_puerto', 'label': 'Puerto a puerto'},
{'code': 'puerto_puerta', 'label': 'Puerto a puerta'},
{'code': 'puerta_puerto', 'label': 'Puerta a puerto'},
{'code': 'puerta_puerta', 'label': 'Puerta a puerta'}]},
'prioridad': {'label': 'Prioridad',
'is_system': False,
'items': [{'code': 'baja', 'label': 'Baja'},
{'code': 'normal', 'label': 'Normal'},
{'code': 'alta', 'label': 'Alta'},
{'code': 'urgente', 'label': 'Urgente'}]},
'tipo_mercancia': {'label': 'Tipo de mercancía',
'is_system': False,
'items': [{'code': 'general', 'label': 'Carga general'},
{'code': 'perecedera', 'label': 'Perecedera'},
{'code': 'peligrosa', 'label': 'Peligrosa (IMO)'},
{'code': 'refrigerada', 'label': 'Refrigerada'},
{'code': 'granel', 'label': 'Granel'},
{'code': 'sobredimensionada', 'label': 'Sobredimensionada'},
{'code': 'valiosa', 'label': 'Valiosa'},
{'code': 'otro', 'label': 'Otro'}]},
'unidad_medida': {'label': 'Unidad de medida',
'is_system': False,
'items': [{'code': 'cm', 'label': 'Centímetros (cm)'},
{'code': 'm', 'label': 'Metros (m)'},
{'code': 'in', 'label': 'Pulgadas (in)'},
{'code': 'ft', 'label': 'Pies (ft)'},
{'code': 'kg', 'label': 'Kilogramos (kg)'},
{'code': 'lb', 'label': 'Libras (lb)'},
{'code': 'm3', 'label': 'Metros cúbicos (m³)'}]},
'tipo_embalaje': {'label': 'Tipo de embalaje',
'is_system': False,
'items': [{'code': 'caja', 'label': 'Caja'},
{'code': 'pallet', 'label': 'Pallet'},
{'code': 'tarima', 'label': 'Tarima'},
{'code': 'huacal', 'label': 'Huacal'},
{'code': 'saco', 'label': 'Saco'},
{'code': 'tambor', 'label': 'Tambor'},
{'code': 'rollo', 'label': 'Rollo'},
{'code': 'atado', 'label': 'Atado'},
{'code': 'granel', 'label': 'Granel'},
{'code': 'otro', 'label': 'Otro'}]},
'servicio_adicional': {'label': 'Servicios adicionales',
'is_system': False,
'items': [{'code': 'seguro', 'label': 'Seguro de la mercancía'},
{'code': 'despacho_aduanal', 'label': 'Despacho aduanal'},
{'code': 'transporte_terrestre', 'label': 'Transporte terrestre'},
{'code': 'almacenaje', 'label': 'Almacenaje'},
{'code': 'maniobras', 'label': 'Maniobras'},
{'code': 'custodia', 'label': 'Custodia'},
{'code': 'revalidacion', 'label': 'Revalidación'},
{'code': 'inspeccion', 'label': 'Inspección'},
{'code': 'otro', 'label': 'Otro'}]},
'tipo_documento': {'label': 'Tipo de documento',
'is_system': False,
'items': [{'code': 'factura_comercial', 'label': 'Factura comercial'},
{'code': 'packing_list', 'label': 'Packing list'},
{'code': 'certificado_origen', 'label': 'Certificado de origen'},
{'code': 'hoja_seguridad_msds', 'label': 'Hoja de seguridad (MSDS)'},
{'code': 'ficha_tecnica', 'label': 'Ficha técnica'},
{'code': 'carta_instrucciones', 'label': 'Carta de instrucciones'},
{'code': 'otro', 'label': 'Otro'}]},
'incoterm': {'label': 'Incoterm (2020)',
'is_system': True,
'items': [{'code': 'EXW', 'label': 'EXW — Ex Works (en fábrica)'},
{'code': 'FCA', 'label': 'FCA — Free Carrier (franco transportista)'},
{'code': 'FAS', 'label': 'FAS — Free Alongside Ship (franco al costado del buque)'},
{'code': 'FOB', 'label': 'FOB — Free On Board (franco a bordo)'},
{'code': 'CFR', 'label': 'CFR — Cost and Freight (costo y flete)'},
{'code': 'CIF', 'label': 'CIF — Cost, Insurance and Freight (costo, seguro y flete)'},
{'code': 'CPT', 'label': 'CPT — Carriage Paid To (transporte pagado hasta)'},
{'code': 'CIP', 'label': 'CIP — Carriage and Insurance Paid To (transporte y seguro pagados hasta)'},
{'code': 'DAP', 'label': 'DAP — Delivered At Place (entregado en lugar)'},
{'code': 'DPU', 'label': 'DPU — Delivered At Place Unloaded (entregado en lugar descargado)'},
{'code': 'DDP', 'label': 'DDP — Delivered Duty Paid (entregado con derechos pagados)'}]},
})
# Formas de pago SAT de un dígito → dos dígitos (01, 02, 03, 04, 05, 06, 08).
# El SAT exige dos posiciones; se corrige el catálogo base.
for _fp in GLOBAL_CATALOGS.get('forma_pago', {}).get('items', []):
if len(_fp['code']) == 1:
_fp['code'] = _fp['code'].zfill(2)
# Ubicaciones por país (ciudad/puerto/aeropuerto), dependientes de `pais`.
from .seed_locations import LOCATION_CATALOGS # noqa: E402
GLOBAL_CATALOGS.update(LOCATION_CATALOGS)

79
backend/api/v1/modules/crm/catalogs/seed_locations.py Normal file
View File

@@ -0,0 +1,79 @@
"""Catálogos de ubicaciones por país: ciudad, puerto (UN/LOCODE), aeropuerto (IATA).
Dependientes de `pais` (`parent_catalog='pais'`, `parent_code=<ISO3>`). Curado a las
rutas de comercio más usadas (extensible: agregar países/nodos según tarifarios).
Los códigos de puerto/aeropuerto se alinean con los que usan las lanes del tarifario
para que el Cotizador encuentre ruta.
"""
# (ISO3, ciudades[(code,label)], puertos[(code,label)], aeropuertos[(code,label)])
_LOC = [
("MEX",
[("MX-CDMX", "Ciudad de México"), ("MX-GDL", "Guadalajara"), ("MX-MTY", "Monterrey"),
("MX-QRO", "Querétaro"), ("MX-TIJ", "Tijuana"), ("MX-VER", "Veracruz")],
[("MXZLO", "Manzanillo"), ("MXVER", "Veracruz"), ("MXATM", "Altamira"),
("MXLZC", "Lázaro Cárdenas"), ("MXPGO", "Progreso"), ("MXESE", "Ensenada")],
[("MEX", "AICM Ciudad de México"), ("NLU", "AIFA Santa Lucía"), ("GDL", "Guadalajara"),
("MTY", "Monterrey"), ("TIJ", "Tijuana"), ("CUN", "Cancún")]),
("USA",
[("US-LAX", "Los Ángeles"), ("US-NYC", "Nueva York"), ("US-HOU", "Houston"),
("US-CHI", "Chicago"), ("US-MIA", "Miami"), ("US-LRD", "Laredo")],
[("USLAX", "Los Angeles"), ("USLGB", "Long Beach"), ("USNYC", "Nueva York/NJ"),
("USHOU", "Houston"), ("USSAV", "Savannah"), ("USSEA", "Seattle"), ("USOAK", "Oakland")],
[("LAX", "Los Ángeles"), ("JFK", "Nueva York JFK"), ("ORD", "Chicago O'Hare"),
("MIA", "Miami"), ("DFW", "Dallas Fort Worth"), ("ATL", "Atlanta")]),
("CHN",
[("CN-SHA", "Shanghái"), ("CN-SZX", "Shenzhen"), ("CN-CAN", "Guangzhou"),
("CN-NGB", "Ningbo"), ("CN-TAO", "Qingdao"), ("CN-PEK", "Pekín")],
[("CNSHA", "Shanghái"), ("CNNGB", "Ningbo"), ("CNSZX", "Shenzhen"),
("CNTAO", "Qingdao"), ("CNCAN", "Guangzhou"), ("CNXMN", "Xiamen"), ("CNTXG", "Tianjin")],
[("PVG", "Shanghái Pudong"), ("PEK", "Pekín Capital"), ("CAN", "Guangzhou"),
("SZX", "Shenzhen"), ("HKG", "Hong Kong")]),
("DEU",
[("DE-HAM", "Hamburgo"), ("DE-FRA", "Fráncfort"), ("DE-MUC", "Múnich"), ("DE-BER", "Berlín")],
[("DEHAM", "Hamburgo"), ("DEBRV", "Bremerhaven")],
[("FRA", "Fráncfort"), ("MUC", "Múnich"), ("HAM", "Hamburgo")]),
("ESP",
[("ES-MAD", "Madrid"), ("ES-BCN", "Barcelona"), ("ES-VLC", "Valencia")],
[("ESVLC", "Valencia"), ("ESBCN", "Barcelona"), ("ESALG", "Algeciras")],
[("MAD", "Madrid Barajas"), ("BCN", "Barcelona")]),
("NLD",
[("NL-RTM", "Róterdam"), ("NL-AMS", "Ámsterdam")],
[("NLRTM", "Róterdam")],
[("AMS", "Ámsterdam Schiphol")]),
("BRA",
[("BR-SAO", "São Paulo"), ("BR-SSZ", "Santos"), ("BR-RIO", "Río de Janeiro")],
[("BRSSZ", "Santos"), ("BRPNG", "Paranaguá"), ("BRRIG", "Rio Grande")],
[("GRU", "São Paulo Guarulhos"), ("GIG", "Río de Janeiro")]),
("CAN",
[("CA-YVR", "Vancouver"), ("CA-YYZ", "Toronto"), ("CA-YMQ", "Montreal")],
[("CAVAN", "Vancouver"), ("CAMTR", "Montreal"), ("CAHAL", "Halifax")],
[("YVR", "Vancouver"), ("YYZ", "Toronto Pearson")]),
("JPN",
[("JP-TYO", "Tokio"), ("JP-OSA", "Osaka"), ("JP-YOK", "Yokohama")],
[("JPYOK", "Yokohama"), ("JPTYO", "Tokio"), ("JPNGO", "Nagoya"), ("JPKOB", "Kobe")],
[("NRT", "Tokio Narita"), ("HND", "Tokio Haneda"), ("KIX", "Osaka Kansai")]),
("KOR",
[("KR-SEL", "Seúl"), ("KR-PUS", "Busan")],
[("KRPUS", "Busan"), ("KRINC", "Incheon")],
[("ICN", "Seúl Incheon")]),
]
def _build() -> dict:
ciudad, puerto, aeropuerto = [], [], []
for iso3, cities, ports, airports in _LOC:
for code, label in cities:
ciudad.append({"code": code, "label": label, "parent_catalog": "pais", "parent_code": iso3})
for code, label in ports:
puerto.append({"code": code, "label": f"{label} ({code})", "parent_catalog": "pais", "parent_code": iso3})
for code, label in airports:
aeropuerto.append({"code": code, "label": f"{label} ({code})", "parent_catalog": "pais", "parent_code": iso3})
return {
"ciudad": {"label": "Ciudad", "is_system": True, "items": ciudad},
"puerto": {"label": "Puerto", "is_system": True, "items": puerto},
"aeropuerto": {"label": "Aeropuerto", "is_system": True, "items": aeropuerto},
}
LOCATION_CATALOGS = _build()

168
backend/api/v1/modules/crm/catalogs/service.py Normal file
View File

@@ -0,0 +1,168 @@
"""Lógica de negocio de los catálogos de referencia del CRM."""
from typing import Any
from fastapi import HTTPException, status
from sqlalchemy import and_, or_
from sqlalchemy.orm import Session
from core.security import is_hub_admin
from .dto import CatalogItemCreate, CatalogItemUpdate, CatalogMeta
from .models import CatalogItem
from .seed_data import GLOBAL_CATALOGS, TENANT_CATALOG_LABELS
# Metadata de catálogos (labels y si el cliente puede llenarlos).
CATALOG_LABELS: dict[str, str] = {k: v["label"] for k, v in GLOBAL_CATALOGS.items()}
CATALOG_LABELS.update(TENANT_CATALOG_LABELS)
# Catálogos que administra el cliente (tenant). El resto son globales (Aduanasoft).
TENANT_CATALOG_KEYS = set(TENANT_CATALOG_LABELS.keys())
KNOWN_CATALOGS = set(CATALOG_LABELS.keys())
def _require_known(catalog: str) -> None:
if catalog not in KNOWN_CATALOGS:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Catálogo '{catalog}' no existe")
def list_meta(db: Session, tenant_id: int) -> list[CatalogMeta]:
"""Lista todos los catálogos disponibles con su conteo (global + del tenant)."""
out: list[CatalogMeta] = []
for key, label in CATALOG_LABELS.items():
is_tenant = key in TENANT_CATALOG_KEYS
count = (
db.query(CatalogItem)
.filter(
CatalogItem.catalog == key,
or_(CatalogItem.tenant_id.is_(None), CatalogItem.tenant_id == tenant_id),
)
.count()
)
out.append(
CatalogMeta(
catalog=key,
label=label,
scope="tenant" if is_tenant else "global",
is_system=bool(GLOBAL_CATALOGS.get(key, {}).get("is_system", False)),
count=count,
)
)
return out
def list_items(
db: Session,
catalog: str,
tenant_id: int,
parent_code: str | None = None,
include_inactive: bool = False,
) -> list[CatalogItem]:
_require_known(catalog)
q = db.query(CatalogItem).filter(
CatalogItem.catalog == catalog,
or_(CatalogItem.tenant_id.is_(None), CatalogItem.tenant_id == tenant_id),
)
if not include_inactive:
q = q.filter(CatalogItem.is_active.is_(True))
if parent_code:
q = q.filter(CatalogItem.parent_code == parent_code)
return q.order_by(CatalogItem.sort_order, CatalogItem.label).all()
def _resolve_write_scope(catalog: str, scope: str | None, current_user: dict) -> int | None:
"""Devuelve el tenant_id a usar al escribir (None = global) y valida permisos.
- scope 'global' → solo hub_admin puede tocar catálogos globales (Aduanasoft).
- scope 'tenant' (default) → se guarda en el tenant del usuario.
"""
wants_global = scope == "global"
if wants_global:
if not is_hub_admin(current_user):
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Solo un administrador de Aduanasoft puede editar catálogos globales.",
)
return None
return int(current_user["tenant_id"])
def create_item(
db: Session, catalog: str, data: CatalogItemCreate, current_user: dict, scope: str | None = None
) -> CatalogItem:
_require_known(catalog)
target_tenant = _resolve_write_scope(catalog, scope, current_user)
# No duplicar por (catalog, code, tenant_id)
exists = (
db.query(CatalogItem)
.filter(
CatalogItem.catalog == catalog,
CatalogItem.code == data.code,
CatalogItem.tenant_id.is_(None) if target_tenant is None else CatalogItem.tenant_id == target_tenant,
)
.first()
)
if exists:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail=f"Ya existe la clave '{data.code}' en el catálogo '{catalog}'.",
)
item = CatalogItem(
catalog=catalog,
code=data.code,
label=data.label,
parent_catalog=data.parent_catalog,
parent_code=data.parent_code,
tenant_id=target_tenant,
sort_order=data.sort_order,
is_active=data.is_active,
is_system=False,
created_by=current_user.get("sub"),
updated_by=current_user.get("sub"),
)
db.add(item)
db.commit()
db.refresh(item)
return item
def _get_writable(db: Session, catalog: str, item_id: int, current_user: dict) -> CatalogItem:
_require_known(catalog)
item = db.query(CatalogItem).filter(CatalogItem.id == item_id, CatalogItem.catalog == catalog).first()
if not item:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Elemento no encontrado")
if item.tenant_id is None:
# Global (Aduanasoft): solo hub_admin.
if not is_hub_admin(current_user):
raise HTTPException(
status_code=status.HTTP_403_FORBIDDEN,
detail="Solo un administrador de Aduanasoft puede editar este catálogo global.",
)
elif item.tenant_id != int(current_user["tenant_id"]):
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Elemento no encontrado")
return item
def update_item(
db: Session, catalog: str, item_id: int, data: CatalogItemUpdate, current_user: dict
) -> CatalogItem:
item = _get_writable(db, catalog, item_id, current_user)
payload: dict[str, Any] = data.model_dump(exclude_unset=True)
for field, value in payload.items():
setattr(item, field, value)
item.updated_by = current_user.get("sub")
db.commit()
db.refresh(item)
return item
def delete_item(db: Session, catalog: str, item_id: int, current_user: dict) -> None:
item = _get_writable(db, catalog, item_id, current_user)
if item.is_system:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail="Un catálogo base del sistema no se puede borrar; puedes desactivarlo.",
)
db.delete(item)
db.commit()

0
backend/api/v1/modules/crm/common/__init__.py Normal file
View File

96
backend/api/v1/modules/crm/common/folios.py Normal file
View File

@@ -0,0 +1,96 @@
"""Folios auto-generados del ciclo comercial (Oportunidad → Solicitud → Cotización → Operación).
Formato: ``{LETRA}{AAAA}-{MM}-{NNN}-{DIR}`` (ej. ``O2025-08-001-E``):
- LETRA: entidad — ``O`` Oportunidad, ``S`` Solicitud, ``C`` Cotización, ``OP`` Operación/Embarque.
- ``AAAA-MM``: año-mes de creación.
- ``NNN``: consecutivo **mensual** por compañía y por entidad (reinicia cada mes).
- ``DIR``: ``I`` importación / ``E`` exportación (``X`` si aún no se define la dirección).
El consecutivo se toma de ``crm.folio_counters`` con bloqueo de fila para evitar
duplicados por concurrencia. En SQLite (pruebas) el ``FOR UPDATE`` se ignora sin error;
la unicidad la garantiza el índice único (tenant, company, entity, period).
"""
from __future__ import annotations
from datetime import date
from sqlalchemy import Integer, String, UniqueConstraint, text
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, 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"}
class FolioCounter(Base, TenantScopedMixin, BaseTimestampMixin):
"""Consecutivo mensual por compañía y entidad para armar los folios del ciclo."""
__tablename__ = "folio_counters"
__table_args__ = (
UniqueConstraint(
"tenant_id", "company_id", "entity", "period", name="uq_crm_folio_counters_scope"
),
{"schema": "crm"},
)
id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
entity: Mapped[str] = mapped_column(String(4), nullable=False) # O | S | C | OP
period: Mapped[str] = mapped_column(String(7), nullable=False) # 'AAAA-MM'
last_number: Mapped[int] = mapped_column(Integer, nullable=False, server_default=text("0"))
def direction_suffix(direction: str | None) -> str:
"""Devuelve la letra de dirección del folio (I/E) o 'X' si no está definida."""
return _DIRECTION_SUFFIX.get(direction or "", "X")
def next_folio(
db,
tenant_id: int,
company_id: int,
entity: str,
direction: str | None,
on_date: date | None = None,
with_direction: bool = True,
) -> str:
"""Genera el siguiente folio de una entidad, incrementando su consecutivo mensual.
Reserva el número dentro de la transacción activa (no hace commit): el ``create_*``
que lo invoca es quien confirma junto con la fila recién creada. ``with_direction=False``
omite el sufijo I/E (p. ej. facturas → ``F2026-08-001``).
"""
if entity not in ENTITIES:
raise ValueError(f"Entidad de folio inválida: {entity!r}")
on_date = on_date or date.today()
period = on_date.strftime("%Y-%m")
counter = (
db.query(FolioCounter)
.filter(
FolioCounter.tenant_id == tenant_id,
FolioCounter.company_id == company_id,
FolioCounter.entity == entity,
FolioCounter.period == period,
)
.with_for_update()
.first()
)
if counter is None:
counter = FolioCounter(
tenant_id=tenant_id, company_id=company_id, entity=entity, period=period, last_number=0
)
db.add(counter)
db.flush()
counter.last_number = (counter.last_number or 0) + 1
db.flush()
sequence = f"{counter.last_number:03d}"
if not with_direction:
return f"{entity}{period}-{sequence}"
return f"{entity}{period}-{sequence}-{direction_suffix(direction)}"

37
backend/api/v1/modules/crm/common/pricing.py Normal file
View File

@@ -0,0 +1,37 @@
"""Cálculos de precio compartidos del proceso comercial.
Peso volumétrico / a cobrar de carga aérea (doc maestro de cotización):
P/Vol = (Largo_cm × Ancho_cm × Alto_cm × cantidad) / 6000
El peso a cobrar es el mayor entre el peso bruto y el P/Vol (estándar aéreo).
6000 cm³/kg es el factor internacional (equivale a ~167 kg/m³).
"""
from __future__ import annotations
from decimal import Decimal
# Factor internacional de peso volumétrico aéreo (cm³ por kg).
AIR_VOLUMETRIC_DIVISOR = Decimal("6000")
def _d(value) -> Decimal:
if value is None:
return Decimal(0)
return value if isinstance(value, Decimal) else Decimal(str(value))
def air_volumetric_kg(length_cm, width_cm, height_cm, qty=1) -> Decimal:
"""Peso volumétrico aéreo a partir de dimensiones (cm) y cantidad de bultos.
Devuelve 0 si falta alguna dimensión (no se puede calcular).
"""
length, width, height = _d(length_cm), _d(width_cm), _d(height_cm)
if length <= 0 or width <= 0 or height <= 0:
return Decimal(0)
quantity = _d(qty) if _d(qty) > 0 else Decimal(1)
return (length * width * height * quantity) / AIR_VOLUMETRIC_DIVISOR
def air_chargeable_kg(gross_kg, length_cm, width_cm, height_cm, qty=1) -> Decimal:
"""Peso a cobrar aéreo: max(peso bruto, peso volumétrico por dimensiones)."""
return max(_d(gross_kg), air_volumetric_kg(length_cm, width_cm, height_cm, qty))

4
backend/api/v1/modules/crm/documents/models.py
View File

@@ -22,6 +22,10 @@ class Document(Base, TenantScopedMixin, TimestampMixin):
supplier_id: Mapped[int | None] = mapped_column(
Integer, ForeignKey("crm.suppliers.id"), nullable=True, index=True
)
# Documento adjunto a una solicitud de servicio (factura, packing list, MSDS, etc.)
service_request_id: Mapped[int | None] = mapped_column(
Integer, ForeignKey("crm.service_requests.id"), nullable=True, index=True
)
# constancia_fiscal | acta_constitutiva | identificacion | comprobante_domicilio |
# contrato | presentacion | certificacion | licencia | convenio | tarifario | otro
doc_type: Mapped[str] = mapped_column(String(60), nullable=False)

0
backend/api/v1/modules/crm/expediente_gateway/__init__.py Normal file
View File

64
backend/api/v1/modules/crm/expediente_gateway/doc_types.py Normal file
View File

@@ -0,0 +1,64 @@
"""Catálogo CERRADO de tipos de documento que EFC acepta del CRM.
Estas 22 claves son **exactamente** las de ``TIPOS_DOCUMENTO_CRM`` en
``api/record/views_integrations_crm.py`` de EFC. La lista está duplicada a mano en dos repos con
despliegue independiente, así que ``tests/test_doc_types_paridad.py`` la fija: si alguien agrega un
tipo de un solo lado, ese test se pone rojo antes de que un documento se rechace en producción.
Por qué es un conjunto cerrado y no texto libre, a diferencia del carril de Anexo22 —que manda el
tipo suelto y deja que EFC lo resuelva por nombre—: en el CRM ``doc_type`` es ``String(60)`` /
``String(30)`` **sin validación de backend**, los catálogos viven solo en TypeScript
(``frontend/src/lib/api/crm/format.ts``). Un typo crearía un ``DocumentType`` basura en el catálogo
**global** de EFC, que es compartido por todas las organizaciones y no se limpia solo.
Las tres fuentes del CRM y su origen:
- ``crm.documents`` → ``DOC_TYPES`` de ``format.ts``
- ``ops.shipment_documents`` → ``SHIPMENT_DOC_TYPES`` del mismo archivo
- ``fin.invoices`` → el PDF de factura (``factura_venta``)
``otro`` existe en las dos listas del CRM y significa lo mismo en ambas: es una sola entrada.
"""
# --- crm.documents ---------------------------------------------------------------------------
_TIPOS_DOCUMENTOS_CLIENTE = (
"constancia_fiscal",
"acta_constitutiva",
"identificacion",
"comprobante_domicilio",
"contrato",
"presentacion",
"certificacion",
"licencia",
"convenio",
"tarifario",
)
# --- ops.shipment_documents ------------------------------------------------------------------
_TIPOS_DOCUMENTOS_EMBARQUE = (
"MBL",
"HBL",
"MAWB",
"HAWB",
"CMR",
"factura_comercial",
"packing_list",
"carta_encomienda",
"carta_garantia",
"certificado_permiso",
)
# --- fin.invoices ----------------------------------------------------------------------------
_TIPOS_FACTURACION = ("factura_venta",)
# --- común a varias fuentes -------------------------------------------------------------------
_TIPOS_COMUNES = ("otro",)
EFC_DOC_TYPES: frozenset[str] = frozenset(
_TIPOS_DOCUMENTOS_CLIENTE + _TIPOS_DOCUMENTOS_EMBARQUE + _TIPOS_FACTURACION + _TIPOS_COMUNES
)
def is_valid_doc_type(doc_type: str | None) -> bool:
"""``True`` si EFC va a aceptar ese tipo. Se valida en el CRM para no gastar un viaje de red."""
return bool(doc_type) and doc_type in EFC_DOC_TYPES

131
backend/api/v1/modules/crm/expediente_gateway/models.py Normal file
View File

@@ -0,0 +1,131 @@
"""Outbox transaccional del carril CRM Agentes de Carga -> EFC.
DOS tablas separadas POR PROPÓSITO, igual que en el carril de referencia de Anexo22: una para los
expedientes (metadatos, JSON) y otra para los archivos (binarios que viven en MinIO y se referencian
por su ``s3_key``). Un worker de Celery las drena hacia EFC con reintentos.
**Diferencia con el original, y es necesaria:** aquí las filas se insertan en la MISMA transacción
que el expediente o el documento, porque el CRM es mono-base. En Anexo22 el outbox vivía en otra
base que el pedimento, y ese doble-commit es justamente lo que obligó a inventar el barrido de
huecos. Aquí el barrido se conserva —cubre lo creado antes de activar la integración y cualquier
crash— pero deja de ser el parche de una ventana estructural.
"""
from datetime import datetime
from typing import Optional
from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, Index, Integer, String, Text, text
from sqlalchemy.orm import Mapped, mapped_column
from api.v1.common.base_models import TenantScopedMixin, TimestampMixin
from core.database import Base
# Tipo de trabajo (columna kind) del outbox de EXPEDIENTES.
KIND_EXPEDIENTE = "expediente"
KIND_COMPLETAR = "completar"
# Tipos del outbox de ARCHIVOS (efc_file_outbox).
FILE_KIND_DOCUMENTO = "documento"
# Tablas de origen posibles de un archivo. El CRM tiene DOS tablas de documentos con secuencias
# independientes, así que `source_id` por sí solo es ambiguo: crm.documents.id = 5 y
# ops.shipment_documents.id = 5 coexisten.
SOURCE_CRM_DOCUMENTS = "crm.documents"
SOURCE_OPS_SHIPMENT_DOCUMENTS = "ops.shipment_documents"
SOURCE_FIN_INVOICES = "fin.invoices"
# Estados (columna status).
STATUS_PENDING = "pending"
STATUS_SENT = "sent"
STATUS_FAILED = "failed"
# Tope de reintentos antes de marcar 'failed' (reconciliación / reintento manual).
# Heredado del carril de Anexo22. Con barridos de 120 s son ~17 minutos de insistencia antes de
# rendirse y dejar la fila visible para que una persona la reintente a mano.
MAX_ATTEMPTS = 8
class EfcSyncOutbox(Base, TenantScopedMixin, TimestampMixin):
"""Cola de metadatos hacia EFC: crear el expediente provisional y completarlo."""
__tablename__ = "efc_sync_outbox"
__table_args__ = (
Index("ix_crm_efc_sync_outbox_status", "status"),
Index("ix_crm_efc_sync_outbox_kind_status", "kind", "status"),
{"schema": "crm"},
)
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
kind: Mapped[str] = mapped_column(String(20), nullable=False)
# Datos para construir el request a EFC (folio, storage_token, tenant slug, company, y la data
# aduanera si el kind es 'completar').
payload: Mapped[dict] = mapped_column(JSON, nullable=False)
# id local del expediente (crm.cases.id) que originó la fila.
expediente_ref: Mapped[Optional[int]] = mapped_column(Integer, nullable=True, index=True)
# Ciclo de vida.
status: Mapped[str] = mapped_column(String(10), nullable=False, server_default=text(f"'{STATUS_PENDING}'"))
attempts: Mapped[int] = mapped_column(Integer, nullable=False, server_default=text("0"))
last_error: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
sent_at: Mapped[Optional[datetime]] = mapped_column(DateTime, nullable=True)
# Acuse de EFC al confirmar (trazabilidad).
efc_pedimento_id: Mapped[Optional[str]] = mapped_column(String(36), nullable=True)
class EfcFileOutbox(Base, TenantScopedMixin, TimestampMixin):
"""Cola de ARCHIVOS hacia EFC.
El binario vive en el MinIO del CRM (durable); esta fila referencia su ``s3_key`` y el expediente
destino. El worker lo sube a EFC y, con ``delete_local`` (corte directo), BORRA la copia local al
confirmar la entrega.
``delete_local`` **es el mecanismo de «EFC es la fuente única»**: "solo EFC" es el estado FINAL
(eventual), no el inmediato. Entre que el usuario sube el archivo y que EFC lo confirma, la copia
local es lo único que hay, y borrarla antes perdería el archivo si la entrega fallara.
``source_table`` es un añadido necesario sobre el original de Anexo22, que solo llevaba
``source_id``. El CRM tiene dos tablas de documentos con secuencias independientes, así que un
entero solo es ambiguo entre ellas. Es el mismo problema que Anexo22 resolvió con su mapa por
``kind``, y su comentario dice qué pasa si se ignora: un UPDATE con el id de otra tabla **vacía la
columna de un documento ajeno** que tuviera ese mismo entero — daño en el dato de otro, sin un
solo error visible. Un ``(kind, source_table)`` que no esté en el mapa **no toca nada**, en vez
de caer por omisión.
"""
__tablename__ = "efc_file_outbox"
__table_args__ = (
Index("ix_crm_efc_file_outbox_status", "status"),
Index("ix_crm_efc_file_outbox_kind_status", "kind", "status"),
Index("ix_crm_efc_file_outbox_source", "source_table", "source_id"),
{"schema": "crm"},
)
id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
kind: Mapped[str] = mapped_column(String(30), nullable=False)
# Objeto en MinIO a subir + metadata para el upload a EFC.
s3_key: Mapped[str] = mapped_column(String(1024), nullable=False)
file_name: Mapped[str] = mapped_column(String(255), nullable=False)
content_type: Mapped[Optional[str]] = mapped_column(String(100), nullable=True)
efc_tipo: Mapped[str] = mapped_column(String(40), nullable=False) # tipo de documento en EFC
# Origen: la pareja (tabla, id) desambigua entre las dos secuencias de documentos del CRM.
source_table: Mapped[str] = mapped_column(String(30), nullable=False)
source_id: Mapped[Optional[int]] = mapped_column(Integer, nullable=True)
# El handle autoritativo que viaja a EFC y garantiza la idempotencia del lado de allá.
crm_document_ref: Mapped[Optional[str]] = mapped_column(String(64), nullable=True)
expediente_ref: Mapped[int] = mapped_column(
Integer, ForeignKey("crm.cases.id"), nullable=False, index=True
)
delete_local: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("true"))
# Ciclo de vida.
status: Mapped[str] = mapped_column(String(10), nullable=False, server_default=text(f"'{STATUS_PENDING}'"))
attempts: Mapped[int] = mapped_column(Integer, nullable=False, server_default=text("0"))
last_error: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
sent_at: Mapped[Optional[datetime]] = mapped_column(DateTime, nullable=True)
efc_document_id: Mapped[Optional[str]] = mapped_column(String(36), nullable=True)

58
backend/api/v1/modules/crm/expediente_gateway/routes.py Normal file
View File

@@ -0,0 +1,58 @@
"""Endpoints de operación y observabilidad del carril CRM -> EFC.
Tablero mínimo para ver y reintentar la entrega de expedientes y documentos a EFC. Autenticado con
el auth normal del CRM y acotado por tenant/company, como el resto del módulo.
Montado bajo ``/v1/crm`` → ``/v1/crm/expediente-gateway/...``
"""
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy.orm import Session
from core.database import get_core_db
from core.security import get_current_user
from . import service
router = APIRouter(prefix="/expediente-gateway", tags=["EFC Gateway (ops)"])
@router.get("/outbox")
def list_outbox(
company_id: int = Query(..., description="Company ID"),
tipo: str | None = Query(None, description="Filtrar por tabla: sync|file"),
status: str | None = Query(None, description="Filtrar por status: pending|sent|failed"),
limit: int = Query(100, ge=1, le=500),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Filas de los dos outbox, para ver los fallos y su ``last_error``."""
return service.list_outbox(db, current_user["tenant_id"], company_id, tipo, status, limit)
@router.post("/outbox/{outbox_id}/retry")
def retry_outbox(
outbox_id: int,
company_id: int = Query(..., description="Company ID"),
tipo: str = Query("file", description="Tabla de la fila: sync|file"),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Reintento manual de una fila: la resetea a ``pending`` y la re-despacha.
Una fila inexistente devuelve **404 con mensaje específico**, no un 200 silencioso: el frontend
pinta el botón de reintento según lo que reciba, y un 200 le haría creer que la entrega volvió a
la cola cuando no hay nada que entregar.
"""
ok = service.retry_outbox_row(db, outbox_id, current_user["tenant_id"], company_id, tipo)
if not ok:
raise HTTPException(status_code=404, detail="Fila de outbox no encontrada")
return {"status": "requeued", "id": outbox_id}
@router.get("/metrics")
def metrics(
company_id: int = Query(..., description="Company ID"),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Conteo de los dos outbox por status (pending/sent/failed) para monitoreo."""
return service.outbox_metrics(db, current_user["tenant_id"], company_id)

755
backend/api/v1/modules/crm/expediente_gateway/service.py Normal file
View File

@@ -0,0 +1,755 @@
"""Carril CRM Agentes de Carga -> EFC: encolado, entrega y reconciliación.
Clon del gateway de Anexo22 (``anexo22/.../pedimentos/pedimento_gateway/service.py``), que es el
carril de referencia ya en producción. Quien conozca uno debe poder leer el otro, así que la tabla
de equivalencias va aquí:
====================================== ======================================
Anexo22 CRM
====================================== ======================================
``replicate_pedimento_best_effort`` ``replicate_expediente_best_effort``
``_enqueue_pedimento_outbox`` ``_enqueue_expediente_outbox``
``_dispatch_delivery`` igual
``deliver_row`` / ``_deliver_pedimento`` ``deliver_row`` / ``_deliver_expediente``
``_register_failure`` **idéntico**
``_ya_entregado(source_id, kind)`` ``_ya_entregado(source_table, source_id, kind)``
``deliver_file_row`` **idéntico**, con ensure-then-upload y ``delete_local``
``_register_file_failure`` **idéntico**
``_resolve_org_id`` + ``_org_id_cache`` igual — dict módulo-global, por worker, sin invalidación
``list_outbox`` / ``retry_outbox_row`` / ``outbox_metrics`` igual, para las dos tablas
``find_pedimento_gaps`` ``find_expediente_gaps``
====================================== ======================================
**La máquina de reintentos tiene tres capas y las tres se conservan:**
1. En el cliente HTTP: 3 intentos, backoff lineal ``0.15 * (attempt + 1)``, corte seco en 4xx.
2. En el worker: ``deliver_row`` **nunca lanza**; registra el fallo en la propia fila.
3. En el beat: barridos cada 120 s que re-despachan lo ``pending``.
No hay ``autoretry_for``, ``retry_backoff`` ni ``max_retries`` en las tareas: duplicarían el
mecanismo que ya está en el cliente y en el barrido.
**Cuatro guardas de idempotencia**, en este orden:
1. ``_ya_entregado(source_table, source_id, kind)`` antes de encolar.
2. ``if row.status == STATUS_SENT: return`` al entrar a entregar.
3. El ``crm_document_ref`` que viaja con la subida: EFC devuelve 200 con el que ya existía.
4. El UNIQUE parcial del lado de EFC — la única que garantiza la base.
**Por qué ``find_expediente_gaps`` sigue aquí aunque el CRM sea mono-base.** En Anexo22 el outbox se
commitea aparte del pedimento (dos bases distintas) y ese doble-commit es lo que obligó a inventar el
barrido de huecos. Aquí la fila del outbox va en la MISMA transacción que el expediente, así que esa
ventana no existe. El barrido se conserva porque cubre otras dos cosas: los expedientes creados
**antes** de activar la integración, y cualquier crash. Queda escrito para que el siguiente que lo
lea no lo borre creyendo que es redundante.
"""
import logging
from contextlib import contextmanager
from datetime import datetime, timezone
from typing import Optional
from sqlalchemy.orm import Session
from core.config import settings
from core.database import scoped_core_db
from core.efc_client import EfcClient, EfcClientError, efc_client
from ..cases.models import Case
from .models import (
KIND_COMPLETAR,
KIND_EXPEDIENTE,
MAX_ATTEMPTS,
STATUS_FAILED,
STATUS_PENDING,
STATUS_SENT,
EfcFileOutbox,
EfcSyncOutbox,
)
logger = logging.getLogger(__name__)
# Cache de organización EFC por slug de tenant. Dict módulo-global: vive por worker y NO se
# invalida, igual que el del carril de Anexo22. Es correcto porque la organización de un tenant no
# cambia de id: el resolver de EFC es idempotente y devuelve siempre la misma. Si algún día pudiera
# cambiar, reiniciar el worker la vuelve a resolver.
_org_id_cache: dict[str, str] = {}
@contextmanager
def _savepoint(db: Session):
"""Aísla un encolado dentro de la transacción del usuario con un SAVEPOINT.
**Esto es lo único del encolado que NO se clona del carril de Anexo22, y la razón es de fondo.**
Allá el outbox vive en otra base que el pedimento, así que su ``except`` podía hacer
``db.rollback()`` sin consecuencias: revertía la sesión del outbox y la del pedimento ni se
enteraba.
Aquí el CRM es mono-base y el encolado corre DENTRO de la transacción del usuario. Un
``db.rollback()`` en el ``except`` se llevaría por delante la solicitud y el expediente que el
usuario acaba de crear — exactamente lo contrario de best-effort, y sin un solo error visible
para él. Con el SAVEPOINT, un fallo del encolado deshace **solo** la fila del outbox y la
operación local sigue en pie para que el llamador la commitee.
"""
nested = db.begin_nested()
try:
yield nested
except Exception:
nested.rollback()
raise
# ══ Expediente: encolado y entrega ══════════════════════════════════════════
def replicate_expediente_best_effort(db: Session, expediente: Case) -> None:
"""Encola la réplica del expediente a EFC y dispara la entrega inmediata.
Best-effort en todo: si EFC no está configurado, o si el encolado o el despacho fallan, **no se
propaga el error**. El expediente local ya existe y la operación del usuario no se puede romper
porque un sistema de terceros no conteste. El barrido periódico recoge lo que quede pendiente.
"""
if not settings.EFC_API_URL:
return
row = _enqueue_expediente_outbox(db, expediente)
if row is None:
return
_dispatch_delivery(row.id, row.tenant_id, row.company_id)
def _enqueue_expediente_outbox(db: Session, expediente: Case) -> Optional[EfcSyncOutbox]:
"""Inserta la fila de outbox del expediente. Devuelve ``None`` si falla, sin romper nada.
A diferencia del original, **no commitea**: el CRM es mono-base, así que la fila viaja en la
misma transacción que el expediente. Eso cierra de raíz la ventana del doble-commit que en
Anexo22 obligó a inventar el barrido de huecos.
"""
try:
if _expediente_ya_encolado(db, expediente.id):
return None
# Sin folio o sin token no hay nada que replicar: EFC exige los dos y responde
# {'storage_token': ['This field may not be null.']}, que NO es un fallo transitorio.
# Encolarlo de todos modos quemaría los 8 intentos para acabar en `failed`, ensuciando
# el tablero de ops con algo que ningún reintento puede arreglar.
#
# Pasa de verdad en dos casos: expedientes nacidos antes de que existiera el carril
# (los rellena la migración c5d6e7f8a9b0) y aquellos cuyo token no cabe en los 25
# caracteres de `pedimento_app`. Se avisa en WARNING porque es una omisión silenciosa:
# el expediente vive en el CRM y sus documentos nunca llegarán a EFC.
if not expediente.reference or not expediente.efc_storage_token:
logger.warning(
"expediente_gateway: expediente id=%s SIN replicar — folio=%r token=%r. "
"No se encola: EFC rechaza ambos nulos y el reintento no lo arregla.",
expediente.id, expediente.reference, expediente.efc_storage_token,
)
return None
# El slug del tenant NO se resuelve aquí: se rellena al ENTREGAR. Resolverlo ahora abriría
# una segunda sesión de base (``scoped_core_db``) dentro de la transacción del usuario, que
# es justo lo que el encolado debe evitar. Es además lo que hace el carril de referencia.
payload = {
"source": "crm",
"crm_company_id": expediente.company_id,
"crm_expediente_id": expediente.id,
"folio": expediente.reference,
"storage_token": expediente.efc_storage_token,
}
row = EfcSyncOutbox(
kind=KIND_EXPEDIENTE,
payload=payload,
expediente_ref=expediente.id,
status=STATUS_PENDING,
tenant_id=expediente.tenant_id,
company_id=expediente.company_id,
)
with _savepoint(db):
db.add(row)
db.flush()
return row
except Exception:
logger.warning(
"expediente_gateway: no se pudo encolar el expediente id=%s en el outbox",
getattr(expediente, "id", None), exc_info=True,
)
return None
def _expediente_ya_encolado(db: Session, expediente_id: int) -> bool:
"""¿Ya hay una fila viva de alta para este expediente? Evita encolar la misma réplica dos veces."""
return (
db.query(EfcSyncOutbox.id)
.filter(
EfcSyncOutbox.expediente_ref == expediente_id,
EfcSyncOutbox.kind == KIND_EXPEDIENTE,
EfcSyncOutbox.status.in_((STATUS_PENDING, STATUS_SENT)),
)
.first()
is not None
)
def enqueue_completar_best_effort(db: Session, expediente: Case, campos: dict) -> None:
"""Encola el completado del provisional en EFC con la data aduanera real."""
if not settings.EFC_API_URL:
return
try:
row = EfcSyncOutbox(
kind=KIND_COMPLETAR,
payload={
"source": "crm",
"crm_company_id": expediente.company_id,
"crm_expediente_id": expediente.id,
"folio": expediente.reference,
"pedimento": campos,
},
expediente_ref=expediente.id,
status=STATUS_PENDING,
tenant_id=expediente.tenant_id,
company_id=expediente.company_id,
)
with _savepoint(db):
db.add(row)
db.flush()
except Exception:
logger.warning(
"expediente_gateway: no se pudo encolar el completado del expediente id=%s",
getattr(expediente, "id", None), exc_info=True,
)
return
_dispatch_delivery(row.id, row.tenant_id, row.company_id)
def _dispatch_delivery(outbox_id: int, tenant_id: int, company_id: int) -> None:
"""Dispara la tarea de entrega propagando el contexto RLS por headers de Celery.
Best-effort: si el broker no responde, el barrido la recoge. Los headers son obligatorios —
``core/celery_app.py`` materializa el contexto de RLS a partir de ellos, y sin ellos la tarea
corre sin tenant y no ve nada.
"""
try:
from .tasks import deliver_outbox_row # import diferido: evita ciclo con celery_app
deliver_outbox_row.apply_async(
args=[outbox_id, tenant_id, company_id],
headers={"rls_tenant_id": str(tenant_id), "rls_company_id": str(company_id)},
)
except Exception:
logger.warning(
"expediente_gateway: no se pudo despachar la entrega outbox_id=%s (lo tomará el sweep)",
outbox_id, exc_info=True,
)
def deliver_row(db: Session, row: EfcSyncOutbox, client: Optional[EfcClient] = None) -> None:
"""Entrega una fila del outbox de expedientes a EFC. Actualiza estado y ``attempts``.
**No lanza nunca**: los fallos se registran en la propia fila para reconciliación. Un fallo no
puede matar al worker ni perder la intención de entregar.
"""
client = client or efc_client
if not client.is_configured:
logger.info("expediente_gateway: EFC no configurado; se deja pendiente row=%s", row.id)
return
if row.status == STATUS_SENT:
return
try:
if row.kind == KIND_EXPEDIENTE:
_deliver_expediente(db, row, client)
elif row.kind == KIND_COMPLETAR:
_deliver_completar(db, row, client)
else:
row.status = STATUS_FAILED
row.last_error = f"kind desconocido: {row.kind}"
db.commit()
except EfcClientError as exc:
_register_failure(db, row, exc, retryable=exc.retryable)
except Exception as exc: # noqa: BLE001 — cualquier fallo se registra, no rompe el worker
_register_failure(db, row, exc, retryable=True)
def _register_failure(db: Session, row: EfcSyncOutbox, exc: Exception, retryable: bool) -> None:
row.attempts = (row.attempts or 0) + 1
row.last_error = str(exc)[:2000]
if (not retryable) or row.attempts >= MAX_ATTEMPTS:
row.status = STATUS_FAILED
db.commit()
logger.warning(
"expediente_gateway: entrega falló row=%s attempts=%s retryable=%s status=%s: %s",
row.id, row.attempts, retryable, row.status, exc,
)
def _deliver_expediente(db: Session, row: EfcSyncOutbox, client: EfcClient) -> None:
payload = dict(row.payload or {})
org_id = _resolve_org_id(client, row.tenant_id)
payload["organizacion"] = {"efc_organizacion_id": org_id}
payload["crm_tenant_slug"] = _tenant_slug(row.tenant_id)[0] or ""
resp = client.ingest_expediente(payload)
efc = (resp or {}).get("efc") or {}
row.status = STATUS_SENT
row.sent_at = datetime.now(timezone.utc)
row.efc_pedimento_id = efc.get("pedimento_id")
_stamp_expediente_link(db, row.expediente_ref, org_id, efc.get("pedimento_id"))
db.commit()
logger.info(
"expediente_gateway: expediente replicado row=%s efc_pedimento_id=%s",
row.id, row.efc_pedimento_id,
)
def _deliver_completar(db: Session, row: EfcSyncOutbox, client: EfcClient) -> None:
payload = dict(row.payload or {})
org_id = _resolve_org_id(client, row.tenant_id)
payload["organizacion"] = {"efc_organizacion_id": org_id}
payload["crm_tenant_slug"] = _tenant_slug(row.tenant_id)[0] or ""
folio = payload.get("folio")
client.completar_expediente(folio, payload)
row.status = STATUS_SENT
row.sent_at = datetime.now(timezone.utc)
db.commit()
logger.info("expediente_gateway: expediente completado en EFC row=%s folio=%s", row.id, folio)
def _stamp_expediente_link(db: Session, expediente_id: Optional[int], org_id: str,
pedimento_id: Optional[str]) -> None:
"""Refleja en la fila del expediente que EFC ya lo tiene, para que la UI lo pinte.
Es un espejo, no un handle: el CRM sigue hablando de este expediente por su ``folio``. Se guarda
porque el proxy de descarga necesita el ``organizacion_id`` para preguntarle a EFC.
"""
if expediente_id is None:
return
expediente = db.query(Case).filter(Case.id == expediente_id).first()
if expediente is None:
return
expediente.efc_organizacion_id = org_id
if pedimento_id:
expediente.efc_pedimento_id = pedimento_id
expediente.efc_link_state = "LINKED"
expediente.efc_error_code = None
expediente.efc_error_detail = None
# ══ Archivos: encolado y entrega ════════════════════════════════════════════
def _ya_entregado(db: Session, source_table: str, source_id: int, kind: str) -> bool:
"""¿Este archivo ya se entregó al expediente? Evita re-encolar lo que ya está allá.
Sin esta guarda, un reintento encolaba otra entrega del mismo archivo — que además **falla al
leer el objeto local, porque la primera entrega ya lo borró** con ``delete_local``. Ruido en el
log y una fila del outbox condenada a ``failed``.
Lleva ``source_table`` además de ``source_id``, a diferencia del original: el CRM tiene dos
tablas de documentos con secuencias independientes, así que el id solo es ambiguo y esta guarda
se dispararía de más, saltándose la entrega de un documento distinto que casualmente comparte
entero.
"""
return (
db.query(EfcFileOutbox.id)
.filter(
EfcFileOutbox.source_table == source_table,
EfcFileOutbox.source_id == source_id,
EfcFileOutbox.kind == kind,
EfcFileOutbox.status == STATUS_SENT,
)
.first()
is not None
)
def enqueue_file_best_effort(
db: Session,
*,
kind: str,
s3_key: str,
file_name: str,
content_type: Optional[str],
efc_tipo: str,
source_table: str,
source_id: int,
crm_document_ref: str,
expediente_ref: int,
tenant_id: int,
company_id: int,
delete_local: bool = True,
) -> Optional[EfcFileOutbox]:
"""Encola un archivo hacia el expediente de EFC. Devuelve la fila, o ``None`` si no se encoló.
**No commitea**: la fila va en la misma transacción que el documento que la origina, de modo que
no puede existir un documento sin su intención de entrega ni al revés.
"""
if not settings.EFC_API_URL:
return None
if _ya_entregado(db, source_table, source_id, kind):
return None
try:
row = EfcFileOutbox(
kind=kind,
s3_key=s3_key,
file_name=file_name,
content_type=content_type,
efc_tipo=efc_tipo,
source_table=source_table,
source_id=source_id,
crm_document_ref=crm_document_ref,
expediente_ref=expediente_ref,
delete_local=delete_local,
status=STATUS_PENDING,
tenant_id=tenant_id,
company_id=company_id,
)
with _savepoint(db):
db.add(row)
db.flush()
return row
except Exception:
logger.warning(
"expediente_gateway: no se pudo encolar el archivo %s (%s:%s)",
s3_key, source_table, source_id, exc_info=True,
)
return None
def _dispatch_file_delivery(outbox_id: int, tenant_id: int, company_id: int) -> None:
try:
from .tasks import deliver_file_outbox_row # import diferido
deliver_file_outbox_row.apply_async(
args=[outbox_id, tenant_id, company_id],
headers={"rls_tenant_id": str(tenant_id), "rls_company_id": str(company_id)},
)
except Exception:
logger.warning(
"expediente_gateway: no se pudo despachar entrega de archivo outbox_id=%s (lo tomará el sweep)",
outbox_id, exc_info=True,
)
def deliver_file_row(db: Session, row: EfcFileOutbox, client: Optional[EfcClient] = None) -> None:
"""Sube el archivo de ``row.s3_key`` al expediente de EFC y, si ``delete_local``, borra la copia.
**Ensure-then-upload**: si EFC contesta 404 ``expediente_no_encontrado``, la creación del
provisional puede venir en camino (el outbox de expedientes y el de archivos son colas
distintas), así que se asegura el expediente y se reintenta el upload **una** vez.
**No lanza nunca**: como ``deliver_row``, registra el fallo en la propia fila.
"""
client = client or efc_client
if not client.is_configured or row.status == STATUS_SENT:
return
try:
org_id = _resolve_org_id(client, row.tenant_id)
expediente = db.query(Case).filter(Case.id == row.expediente_ref).first()
if expediente is None:
raise EfcClientError(
f"expediente {row.expediente_ref} no encontrado para el archivo '{row.kind}'",
retryable=True,
)
from core.storage_s3 import get_object_bytes
content = get_object_bytes(row.s3_key)
ct = row.content_type or "application/octet-stream"
try:
resp = client.upload_documento(
org_id, row.company_id, expediente.id, row.efc_tipo,
row.file_name, content, ct, crm_document_ref=row.crm_document_ref,
)
except EfcClientError as exc:
if exc.status_code == 404 and exc.code == "expediente_no_encontrado":
# La creación del provisional puede venir en camino: se asegura y se reintenta UNA vez.
client.ingest_expediente({
"source": "crm",
"crm_tenant_slug": (_tenant_slug(row.tenant_id)[0] or ""),
"crm_company_id": row.company_id,
"crm_expediente_id": expediente.id,
"folio": expediente.reference,
"storage_token": expediente.efc_storage_token,
"organizacion": {"efc_organizacion_id": org_id},
})
resp = client.upload_documento(
org_id, row.company_id, expediente.id, row.efc_tipo,
row.file_name, content, ct, crm_document_ref=row.crm_document_ref,
)
else:
raise
doc_id = resp.get("id") if isinstance(resp, dict) else None
if row.delete_local:
try:
from core.storage_s3 import delete_object_if_exists
delete_object_if_exists(row.s3_key)
except Exception:
# Ya está en EFC: no poder borrar la copia local no invalida la entrega.
logger.warning(
"expediente_gateway: no se pudo borrar el archivo local %s (ya en EFC)",
row.s3_key, exc_info=True,
)
row.status = STATUS_SENT
row.sent_at = datetime.now(timezone.utc)
row.efc_document_id = doc_id
db.commit()
_marcar_documento_entregado(db, row, doc_id)
logger.info(
"expediente_gateway: archivo entregado row=%s kind=%s efc_document_id=%s",
row.id, row.kind, doc_id,
)
except EfcClientError as exc:
_register_file_failure(db, row, exc, exc.retryable)
except Exception as exc: # noqa: BLE001
_register_file_failure(db, row, exc, True)
def _register_file_failure(db: Session, row: EfcFileOutbox, exc: Exception, retryable: bool) -> None:
row.attempts = (row.attempts or 0) + 1
row.last_error = str(exc)[:2000]
if (not retryable) or row.attempts >= MAX_ATTEMPTS:
row.status = STATUS_FAILED
db.commit()
_marcar_documento_fallido(db, row, exc)
logger.warning(
"expediente_gateway: entrega de archivo falló row=%s attempts=%s status=%s: %s",
row.id, row.attempts, row.status, exc,
)
# El mapa (kind, source_table) -> modelo del documento de origen. Un par que NO esté aquí **no toca
# nada**, en vez de caer por omisión sobre una tabla cualquiera: escribir con el id de otra tabla
# vaciaría las columnas de un documento ajeno que tuviera ese mismo entero — daño en el dato de otro,
# sin un solo error visible.
def _modelo_de_origen(source_table: str):
if source_table == "crm.documents":
from ..documents.models import Document
return Document
if source_table == "ops.shipment_documents":
from api.v1.modules.ops.shipments.models import ShipmentDocument
return ShipmentDocument
return None
def _fila_de_origen(db: Session, row: EfcFileOutbox):
modelo = _modelo_de_origen(row.source_table)
if modelo is None or row.source_id is None:
return None
return (
db.query(modelo)
.filter(
modelo.id == row.source_id,
modelo.tenant_id == row.tenant_id,
modelo.company_id == row.company_id,
)
.first()
)
def _marcar_documento_entregado(db: Session, row: EfcFileOutbox, doc_id) -> None:
"""Cierra la entrega en la fila del documento: el badge de la UI pasa a «En expediente»."""
documento = _fila_de_origen(db, row)
if documento is None:
return
documento.efc_document_id = str(doc_id) if doc_id else None
documento.efc_sync_state = "SYNCED"
documento.efc_synced_at = datetime.now(timezone.utc)
documento.efc_error_code = None
documento.efc_error_detail = None
if row.delete_local:
# El objeto local ya no está: dejar la key apuntaría a algo inexistente y la descarga se
# ramificaría por el camino equivocado.
documento.file_key = None
db.commit()
def _marcar_documento_fallido(db: Session, row: EfcFileOutbox, exc: Exception) -> None:
"""Refleja el fallo en la fila del documento para que la ficha lo muestre sin ir a los logs."""
documento = _fila_de_origen(db, row)
if documento is None:
return
documento.efc_attempts = row.attempts
documento.efc_error_detail = str(exc)[:2000]
documento.efc_error_code = getattr(exc, "code", None)
if row.status == STATUS_FAILED:
documento.efc_sync_state = "FAILED"
db.commit()
# ══ Organización ════════════════════════════════════════════════════════════
def _resolve_org_id(client: EfcClient, tenant_id: int) -> str:
slug, name = _tenant_slug(tenant_id)
if not slug:
raise EfcClientError(
f"tenant {tenant_id} sin slug; no se puede resolver la organización EFC.",
retryable=False,
)
if slug in _org_id_cache:
return _org_id_cache[slug]
resp = client.resolve_organizacion(slug, name)
org_id = resp.get("id") if isinstance(resp, dict) else None
if not org_id:
raise EfcClientError("El resolver de organización de EFC no devolvió id.", retryable=True)
_org_id_cache[slug] = org_id
return org_id
def _tenant_slug(tenant_id: int) -> tuple[Optional[str], Optional[str]]:
from api.v1.modules.core.tenants.models import Tenant
with scoped_core_db(tenant_id=tenant_id) as db:
t = db.query(Tenant).filter(Tenant.id == tenant_id).first()
if t is None:
return None, None
return t.slug, t.name
# ══ Tablero de ops ══════════════════════════════════════════════════════════
def _outbox_to_dict(r: EfcSyncOutbox) -> dict:
return {
"id": r.id,
"tabla": "sync",
"kind": r.kind,
"status": r.status,
"attempts": r.attempts,
"last_error": r.last_error,
"expediente_ref": r.expediente_ref,
"efc_pedimento_id": r.efc_pedimento_id,
"created_at": r.created_at.isoformat() if r.created_at else None,
"sent_at": r.sent_at.isoformat() if r.sent_at else None,
}
def _file_outbox_to_dict(r: EfcFileOutbox) -> dict:
return {
"id": r.id,
"tabla": "file",
"kind": r.kind,
"status": r.status,
"attempts": r.attempts,
"last_error": r.last_error,
"expediente_ref": r.expediente_ref,
"file_name": r.file_name,
"efc_tipo": r.efc_tipo,
"source_table": r.source_table,
"source_id": r.source_id,
"crm_document_ref": r.crm_document_ref,
"efc_document_id": r.efc_document_id,
"created_at": r.created_at.isoformat() if r.created_at else None,
"sent_at": r.sent_at.isoformat() if r.sent_at else None,
}
def list_outbox(db: Session, tenant_id: int, company_id: int, tipo: Optional[str] = None,
status: Optional[str] = None, limit: int = 100) -> list[dict]:
"""Lista filas de los DOS outbox para el tablero de ops. ``tipo`` ∈ ``sync`` | ``file``."""
salida: list[dict] = []
if tipo in (None, "", "sync"):
q = db.query(EfcSyncOutbox).filter(
EfcSyncOutbox.tenant_id == tenant_id, EfcSyncOutbox.company_id == company_id
)
if status:
q = q.filter(EfcSyncOutbox.status == status)
salida += [
_outbox_to_dict(r)
for r in q.order_by(EfcSyncOutbox.created_at.desc()).limit(limit).all()
]
if tipo in (None, "", "file"):
q = db.query(EfcFileOutbox).filter(
EfcFileOutbox.tenant_id == tenant_id, EfcFileOutbox.company_id == company_id
)
if status:
q = q.filter(EfcFileOutbox.status == status)
salida += [
_file_outbox_to_dict(r)
for r in q.order_by(EfcFileOutbox.created_at.desc()).limit(limit).all()
]
salida.sort(key=lambda d: (d.get("created_at") or ""), reverse=True)
return salida[:limit]
def retry_outbox_row(db: Session, outbox_id: int, tenant_id: int, company_id: int,
tipo: str = "file") -> bool:
"""Reintento manual: resetea la fila a ``pending`` (``attempts=0``) y la re-despacha.
Devuelve ``False`` si no existe para ese tenant/company — el llamador lo traduce a **404 con
mensaje específico**, no a un 200 silencioso: es contrato con el frontend, que pinta el botón
según lo que reciba.
"""
modelo = EfcSyncOutbox if tipo == "sync" else EfcFileOutbox
r = (
db.query(modelo)
.filter(modelo.id == outbox_id, modelo.tenant_id == tenant_id, modelo.company_id == company_id)
.first()
)
if r is None:
return False
r.status = STATUS_PENDING
r.attempts = 0
r.last_error = None
db.commit()
if tipo == "sync":
_dispatch_delivery(r.id, r.tenant_id, r.company_id)
else:
_reset_documento_pendiente(db, r)
_dispatch_file_delivery(r.id, r.tenant_id, r.company_id)
return True
def _reset_documento_pendiente(db: Session, row: EfcFileOutbox) -> None:
documento = _fila_de_origen(db, row)
if documento is None:
return
documento.efc_sync_state = "PENDING"
documento.efc_error_code = None
documento.efc_error_detail = None
db.commit()
def outbox_metrics(db: Session, tenant_id: int, company_id: int) -> dict:
"""Conteo de los dos outbox por status (monitoreo). Los conteos suman las dos tablas."""
from sqlalchemy import func
counts = {STATUS_PENDING: 0, STATUS_SENT: 0, STATUS_FAILED: 0}
for modelo in (EfcSyncOutbox, EfcFileOutbox):
rows = (
db.query(modelo.status, func.count())
.filter(modelo.tenant_id == tenant_id, modelo.company_id == company_id)
.group_by(modelo.status)
.all()
)
for estado, n in rows:
counts[estado] = counts.get(estado, 0) + n
return {
"pending": counts.get(STATUS_PENDING, 0),
"sent": counts.get(STATUS_SENT, 0),
"failed": counts.get(STATUS_FAILED, 0),
}
def find_expediente_gaps(db: Session, limit: int = 200) -> list:
"""Expedientes (no borrados) SIN ninguna fila de outbox que los referencie.
Nunca se encolaron: expedientes creados **antes** de activar la integración, o un crash. Se
re-encolan para no perder la réplica.
Los ``failed`` **no son huecos** —existen como fila, son visibles y reintentables desde el
tablero—, así que la fila los excluye por estar presente, no por su estado. Corre sin contexto
de tenant (beat); cada expediente lleva el suyo.
"""
from sqlalchemy import exists
ya_encolado = exists().where(EfcSyncOutbox.expediente_ref == Case.id)
return (
db.query(Case)
.filter(
Case.deleted_at.is_(None),
~ya_encolado,
# Mismo criterio que el encolado: lo que le falta folio o token no es un hueco
# recuperable, es algo que EFC rechazaría siempre. Sin este filtro la
# reconciliación los reencola cada 5 minutos para verlos fallar de nuevo.
Case.reference.isnot(None),
Case.efc_storage_token.isnot(None),
)
.order_by(Case.id.desc())
.limit(limit)
.all()
)

39
backend/api/v1/modules/crm/expediente_gateway/storage.py Normal file
View File

@@ -0,0 +1,39 @@
"""La llave de almacenamiento del expediente en EFC.
Vive en el carril y no en el módulo del expediente a propósito: el expediente (``crm.cases``) es
del CRM y no sabe nada de EFC; esto es exclusivamente cómo EFC nombra su carpeta.
El generador de folios NO está aquí. Es ``crm/common/folios.py::next_folio``, que ya reserva el
consecutivo mensual por ``(tenant, company, entidad, periodo)`` con bloqueo de fila. El carril lo
consume, no lo reimplementa.
"""
from __future__ import annotations
# Longitud de ``Pedimento.pedimento_app`` en EFC (api/customs/models.py). El token se guarda ahí.
PEDIMENTO_APP_MAX = 25
def storage_token(company_id: int, folio: str) -> str:
"""``CRM-{company_id}-{folio}`` — la llave del pedimento provisional en EFC.
Empieza con letras, así que es imposible que colisione con la llave de un pedimento real, que
es ``^\\d{2}-\\d{2}-\\d{4}-\\d{7}$``. El ``company_id`` va dentro porque el puente con EFC es
tenant → organización 1:1 pero un tenant tiene N companies: sin él, dos companies del mismo
tenant generarían el mismo ``EXP2026-08-001`` y chocarían en el ``unique_together`` de EFC.
PRESUPUESTO DE CARACTERES: ``CRM-`` (4) + company + ``-`` (1) + ``EXP2026-08-001`` (14) = 19 +
los dígitos del company. En los 25 de ``pedimento_app`` caben hasta **6 dígitos** de company,
no 7 como decía la primera versión de este docstring: con 7 salen 26 y el insert del lado de
EFC reventaría. Un consecutivo de 4 dígitos (mes con más de 999 expedientes) gasta uno más.
Se valida en vez de truncar: un token recortado apuntaría a la carpeta de OTRO expediente y
los documentos se mezclarían en silencio, que es peor que fallar aquí.
"""
token = f"CRM-{company_id}-{folio}"
if len(token) > PEDIMENTO_APP_MAX:
raise ValueError(
f"storage_token de {len(token)} caracteres excede los {PEDIMENTO_APP_MAX} de "
f"pedimento_app en EFC: {token!r}. Revisa el largo del company_id o del consecutivo."
)
return token

143
backend/api/v1/modules/crm/expediente_gateway/tasks.py Normal file
View File

@@ -0,0 +1,143 @@
"""Tareas Celery del carril CRM Agentes de Carga -> EFC.
- ``deliver_outbox_row`` / ``sweep_outbox``: expedientes (alta del provisional y completado).
- ``deliver_file_outbox_row`` / ``sweep_file_outbox``: archivos.
- ``sweep_expediente_gaps``: reconciliación de expedientes que nunca se encolaron.
**La trampa de RLS, que es lo que más fácil se pasa por alto.** ``core/celery_app.py`` materializa el
contexto desde los headers ``rls_tenant_id`` / ``rls_company_id``. Por tanto:
- Las tareas **por fila** se despachan siempre con esos headers.
- Los **barridos corren sin contexto de tenant**: leen los ids pendientes con una sesión sin scope y
despachan una tarea hija por fila con sus propios headers. Si un barrido abriera una sesión con
scope e iterara, o no vería nada o se saltaría el aislamiento.
**Sin ``autoretry_for``, ``retry_backoff`` ni ``max_retries``**: duplicarían el mecanismo de
reintento que ya está en el cliente (3 intentos con backoff lineal) y en el barrido (cada 120 s
hasta ``MAX_ATTEMPTS``).
"""
import logging
from core.celery_app import celery_app
from core.config import settings
from core.database import scoped_core_db
from . import service
from .models import STATUS_PENDING, EfcFileOutbox, EfcSyncOutbox
# ── Registro de modelos: NO son imports decorativos, no los quites ──────────────────────
# El worker de Celery NO carga la app: importa este módulo y sus dependencias, y nada más.
# SQLAlchemy resuelve las ForeignKey por NOMBRE de tabla contra su registro global, así que
# si la clase del otro extremo nunca se importó, la configuración de mappers falla con
#
# Foreign key associated with column 'cases.account_id' could not find table 'crm.accounts'
#
# y la tarea muere con PendingRollbackError. El síntoma es cruel: la fila del outbox se
# queda en `pending` con attempts=0 y SIN last_error —porque el fallo ocurre antes de poder
# registrarlo—, así que el carril se ve encolando bien y no entrega nunca. En la app web no
# pasa: `main.py` monta todos los routers y con ellos se importan todos los modelos.
#
# El juego es el mínimo verificado con `configure_mappers()` en un proceso limpio:
# - accounts : cierra la FK cases.account_id, que es la que rompía;
# - documents y ops.shipments : las dos fuentes del outbox de archivos;
# - tenants : lo consulta el resolver de organización al entregar.
from api.v1.modules.core.tenants import models as _m_tenants # noqa: F401
from api.v1.modules.crm.accounts import models as _m_accounts # noqa: F401
from api.v1.modules.crm.documents import models as _m_documents # noqa: F401
from api.v1.modules.ops.shipments import models as _m_shipments # noqa: F401
logger = logging.getLogger(__name__)
# ── Expedientes ─────────────────────────────────────────────────────────────
@celery_app.task(name="expediente_gateway.deliver_outbox_row")
def deliver_outbox_row(outbox_id: int, tenant_id: int, company_id: int) -> None:
with scoped_core_db(tenant_id, company_id) as db:
row = db.query(EfcSyncOutbox).filter(EfcSyncOutbox.id == outbox_id).first()
if row is None:
logger.warning(
"expediente_gateway: outbox_id=%s no encontrado (tenant=%s)", outbox_id, tenant_id
)
return
service.deliver_row(db, row)
@celery_app.task(name="expediente_gateway.sweep_outbox")
def sweep_outbox(limit: int = 100) -> int:
"""Re-despacha filas pendientes de expediente. Sin contexto de tenant: cada fila lleva el suyo."""
with scoped_core_db() as db:
rows = (
db.query(EfcSyncOutbox.id, EfcSyncOutbox.tenant_id, EfcSyncOutbox.company_id)
.filter(EfcSyncOutbox.status == STATUS_PENDING)
.order_by(EfcSyncOutbox.created_at.asc())
.limit(limit)
.all()
)
for rid, tid, cid in rows:
deliver_outbox_row.apply_async(
args=[rid, tid, cid],
headers={"rls_tenant_id": str(tid), "rls_company_id": str(cid) if cid is not None else ""},
)
if rows:
logger.info("expediente_gateway: sweep (expedientes) re-despachó %s filas pendientes", len(rows))
return len(rows)
# ── Archivos ────────────────────────────────────────────────────────────────
@celery_app.task(name="expediente_gateway.deliver_file_outbox_row")
def deliver_file_outbox_row(outbox_id: int, tenant_id: int, company_id: int) -> None:
with scoped_core_db(tenant_id, company_id) as db:
row = db.query(EfcFileOutbox).filter(EfcFileOutbox.id == outbox_id).first()
if row is None:
logger.warning(
"expediente_gateway: file outbox_id=%s no encontrado (tenant=%s)", outbox_id, tenant_id
)
return
service.deliver_file_row(db, row)
@celery_app.task(name="expediente_gateway.sweep_file_outbox")
def sweep_file_outbox(limit: int = 100) -> int:
"""Re-despacha archivos pendientes (EFC o el broker caídos cuando el usuario subió el archivo)."""
with scoped_core_db() as db:
rows = (
db.query(EfcFileOutbox.id, EfcFileOutbox.tenant_id, EfcFileOutbox.company_id)
.filter(EfcFileOutbox.status == STATUS_PENDING)
.order_by(EfcFileOutbox.created_at.asc())
.limit(limit)
.all()
)
for rid, tid, cid in rows:
deliver_file_outbox_row.apply_async(
args=[rid, tid, cid],
headers={"rls_tenant_id": str(tid), "rls_company_id": str(cid) if cid is not None else ""},
)
if rows:
logger.info("expediente_gateway: sweep (archivos) re-despachó %s archivos pendientes", len(rows))
return len(rows)
# ── Reconciliación de huecos ────────────────────────────────────────────────
@celery_app.task(name="expediente_gateway.sweep_expediente_gaps")
def sweep_expediente_gaps(limit: int = 200) -> int:
"""Detecta expedientes que nunca se encolaron a EFC y los re-encola.
No-op si la integración está apagada.
"""
if not settings.EFC_API_URL:
return 0
n = 0
with scoped_core_db() as db:
gaps = service.find_expediente_gaps(db, limit=limit)
for expediente in gaps:
service.replicate_expediente_best_effort(db, expediente)
n += 1
if n:
db.commit()
if n:
logger.info("expediente_gateway: sweep de huecos re-encoló %s expedientes", n)
return n

3
backend/api/v1/modules/crm/leads/dto.py
View File

@@ -11,6 +11,7 @@ class LeadCreate(BaseModel):
phone: str | None = Field(None, max_length=40)
company_name: str | None = Field(None, max_length=255)
source: str | None = Field(None, max_length=60)
preferred_contact_method: str | None = Field(None, max_length=20)
status: str = Field("new", max_length=20)
estimated_value: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=2)
owner_user_id: str | None = Field(None, max_length=64)
@@ -24,6 +25,7 @@ class LeadUpdate(BaseModel):
phone: str | None = Field(None, max_length=40)
company_name: str | None = Field(None, max_length=255)
source: str | None = Field(None, max_length=60)
preferred_contact_method: str | None = Field(None, max_length=20)
status: str | None = Field(None, max_length=20)
estimated_value: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=2)
owner_user_id: str | None = Field(None, max_length=64)
@@ -50,6 +52,7 @@ class LeadResponse(BaseModel):
phone: str | None
company_name: str | None
source: str | None
preferred_contact_method: str | None = None
status: str
estimated_value: Decimal | None
owner_user_id: str | None

2
backend/api/v1/modules/crm/leads/models.py
View File

@@ -19,6 +19,8 @@ class Lead(Base, TenantScopedMixin, TimestampMixin):
company_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
# Origen: web | referido | evento | llamada | email | otro
source: Mapped[str | None] = mapped_column(String(60), nullable=True)
# Medio de contacto preferido (catálogo medio_contacto): llamada|correo|whatsapp|…
preferred_contact_method: Mapped[str | None] = mapped_column(String(20), nullable=True)
# Estado: new | contacted | qualified | unqualified | converted
status: Mapped[str] = mapped_column(String(20), nullable=False, server_default=text("'new'"), index=True)
estimated_value: Mapped[float | None] = mapped_column(Numeric(14, 2), nullable=True)

10
backend/api/v1/modules/crm/opportunities/dto.py
View File

@@ -17,6 +17,7 @@ class OpportunityCreate(BaseModel):
source: str | None = Field(None, max_length=60)
owner_user_id: str | None = Field(None, max_length=64)
notes: str | None = None
operation_type: str | None = Field(None, max_length=20) # importacion | exportacion
class OpportunityUpdate(BaseModel):
@@ -30,10 +31,13 @@ class OpportunityUpdate(BaseModel):
probability: int | None = Field(None, ge=0, le=100)
status: str | None = Field(None, max_length=20)
expected_close_date: date | None = None
won_date: date | None = None
lost_date: date | None = None
lost_reason: str | None = Field(None, max_length=255)
source: str | None = Field(None, max_length=60)
owner_user_id: str | None = Field(None, max_length=64)
notes: str | None = None
operation_type: str | None = Field(None, max_length=20)
class OpportunityMove(BaseModel):
@@ -57,10 +61,16 @@ class OpportunityResponse(BaseModel):
status: str
expected_close_date: date | None
closed_at: datetime | None
won_date: date | None = None
lost_date: date | None = None
lost_reason: str | None
source: str | None
owner_user_id: str | None
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
created_at: datetime

11
backend/api/v1/modules/crm/opportunities/models.py
View File

@@ -34,7 +34,18 @@ class Opportunity(Base, TenantScopedMixin, TimestampMixin):
status: Mapped[str] = mapped_column(String(20), nullable=False, server_default=text("'open'"), index=True)
expected_close_date: Mapped[date | None] = mapped_column(Date, nullable=True)
closed_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
won_date: Mapped[date | None] = mapped_column(Date, nullable=True) # fecha en que se ganó
lost_date: Mapped[date | None] = mapped_column(Date, nullable=True) # fecha en que se perdió
lost_reason: Mapped[str | None] = mapped_column(String(255), nullable=True)
source: Mapped[str | None] = mapped_column(String(60), nullable=True)
owner_user_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
notes: Mapped[str | None] = mapped_column(Text, nullable=True)
# 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
)

19
backend/api/v1/modules/crm/opportunities/service.py
View File

@@ -1,9 +1,11 @@
from datetime import datetime, timezone
from datetime import date, datetime, timezone
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
from .dto import OpportunityCreate, OpportunityUpdate
@@ -46,14 +48,20 @@ def _apply_stage_state(opportunity: Opportunity, stage: PipelineStage) -> None:
opportunity.status = "won"
opportunity.probability = 100
opportunity.closed_at = datetime.now(timezone.utc)
opportunity.won_date = opportunity.won_date or date.today()
opportunity.lost_date = None
elif stage.is_lost:
opportunity.status = "lost"
opportunity.probability = 0
opportunity.closed_at = datetime.now(timezone.utc)
opportunity.lost_date = opportunity.lost_date or date.today()
opportunity.won_date = None
else:
opportunity.status = "open"
opportunity.probability = stage.probability
opportunity.closed_at = None
opportunity.won_date = None
opportunity.lost_date = None
def _validate_refs(db: Session, data: dict, tenant_id: int, company_id: int) -> None:
@@ -149,6 +157,15 @@ def create_opportunity(
if opportunity.stage_id is not None:
stage = _get_scoped_stage(db, opportunity.stage_id, tenant_id, company_id)
_apply_stage_state(opportunity, stage)
# 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)

32
backend/api/v1/modules/crm/quotes/dto.py
View File

@@ -56,6 +56,7 @@ class QuoteBase(BaseModel):
service_request_id: int | None = None
account_id: int | None = None
currency: str = Field("USD", max_length=3)
load_type: str | None = Field(None, max_length=10) # FCL | LCL (variante de la comparación "Ambas")
issue_date: date | None = None
valid_until: date | None = None
notes: str | None = None
@@ -72,6 +73,7 @@ class QuoteUpdate(BaseModel):
service_request_id: int | None = None
account_id: int | None = None
currency: str | None = Field(None, max_length=3)
load_type: str | None = Field(None, max_length=10)
issue_date: date | None = None
valid_until: date | None = None
notes: str | None = None
@@ -83,9 +85,12 @@ class QuoteResponse(QuoteBase):
model_config = ConfigDict(from_attributes=True)
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
pdf_file_key: str | None = None
sent_at: datetime | None = None
accepted_at: datetime | None = None
rejected_at: datetime | None = None
@@ -100,3 +105,30 @@ class QuoteResponse(QuoteBase):
@property
def margin(self) -> Decimal:
return (self.total_sale or Decimal(0)) - (self.total_cost or Decimal(0))
# ----- Configuración de marca del formato de cotización -----
class QuoteSettingsInput(BaseModel):
emitter_name: str | None = Field(None, max_length=255)
emitter_rfc: str | None = Field(None, max_length=13)
emitter_address: str | None = None
emitter_phone: str | None = Field(None, max_length=60)
emitter_email: str | None = Field(None, max_length=255)
emitter_website: str | None = Field(None, max_length=255)
accent_color: str | None = Field(None, max_length=9)
quote_prefix: str | None = Field(None, max_length=12)
default_terms: str | None = None
footer_note: str | None = None
class QuoteSettingsResponse(QuoteSettingsInput):
model_config = ConfigDict(from_attributes=True)
id: int | None = None
logo_file_key: str | None = None
class SendQuoteEmailRequest(BaseModel):
to: str | None = None
subject: str | None = None
message: str | None = None

28
backend/api/v1/modules/crm/quotes/models.py
View File

@@ -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
)
@@ -22,6 +23,8 @@ class Quote(Base, TenantScopedMixin, TimestampMixin):
Integer, ForeignKey("crm.accounts.id"), nullable=True, index=True
)
currency: Mapped[str] = mapped_column(String(3), nullable=False, server_default=text("'USD'"))
# Variante de carga cuando la solicitud es "Ambas": FCL | LCL (NULL si no aplica)
load_type: Mapped[str | None] = mapped_column(String(10), nullable=True)
# borrador | enviada | aceptada | rechazada
status: Mapped[str] = mapped_column(String(20), nullable=False, server_default=text("'borrador'"), index=True)
issue_date: Mapped[date | None] = mapped_column(Date, nullable=True)
@@ -34,10 +37,35 @@ class Quote(Base, TenantScopedMixin, TimestampMixin):
notes: Mapped[str | None] = mapped_column(Text, nullable=True)
terms: Mapped[str | None] = mapped_column(Text, nullable=True)
owner_user_id: Mapped[str | None] = mapped_column(String(64), nullable=True, index=True)
# Clave del PDF generado en MinIO (para regenerar/enviar)
pdf_file_key: Mapped[str | None] = mapped_column(String(512), nullable=True)
created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
class QuoteSettings(Base, TenantScopedMixin, TimestampMixin):
"""Configuración de marca del formato de cotización, por compañía (tenant).
Encabezado del emisor, logo y textos por defecto que se imprimen en el PDF.
"""
__tablename__ = "quote_settings"
__table_args__ = {"schema": "crm"}
id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
emitter_name: Mapped[str | None] = mapped_column(String(255), nullable=True)
emitter_rfc: Mapped[str | None] = mapped_column(String(13), nullable=True)
emitter_address: Mapped[str | None] = mapped_column(Text, nullable=True)
emitter_phone: Mapped[str | None] = mapped_column(String(60), nullable=True)
emitter_email: Mapped[str | None] = mapped_column(String(255), nullable=True)
emitter_website: Mapped[str | None] = mapped_column(String(255), nullable=True)
logo_file_key: Mapped[str | None] = mapped_column(String(512), nullable=True)
accent_color: Mapped[str | None] = mapped_column(String(9), nullable=True, server_default=text("'#2f6bf0'"))
quote_prefix: Mapped[str | None] = mapped_column(String(12), nullable=True, server_default=text("'COT'"))
default_terms: Mapped[str | None] = mapped_column(Text, nullable=True)
footer_note: Mapped[str | None] = mapped_column(Text, nullable=True)
class QuoteItem(Base, TenantScopedMixin, TimestampMixin):
"""Concepto de una cotización (flete, transporte terrestre, despacho, gastos destino, otros)."""

376
backend/api/v1/modules/crm/quotes/pdf.py Normal file
View File

@@ -0,0 +1,376 @@
"""Generador del PDF de Cotización — diseño profesional, sin dependencias de sistema.
Compone un PDF 1.4 byte a byte (Helvetica / Helvetica-Bold) con barras de sección,
tabla de costos con bordes y filas alternadas, caja de totales y logo incrustado
(JPEG /DCTDecode vía Pillow). El branding (emisor, color) viene de la config por tenant.
"""
from __future__ import annotations
import io
from decimal import Decimal
_W = 612
_H = 792
_ML = 50 # margen izquierdo
_MR = 562 # margen derecho (x)
CONCEPT_LABELS = {
"flete_internacional": "Flete internacional",
"transporte_terrestre": "Transporte terrestre",
"despacho_aduanal": "Despacho aduanal",
"gastos_destino": "Gastos en destino",
"otros": "Otros cargos",
}
_TRANSLATE = str.maketrans({"—": "-", "–": "-", "“": '"', "”": '"', "‘": "'", "’": "'", "•": "-", "…": "...", "\t": " "})
def _esc(text) -> str:
s = ("" if text is None else str(text)).translate(_TRANSLATE)
s = s.encode("latin-1", "replace").decode("latin-1")
return s.replace("\\", r"\\").replace("(", r"\(").replace(")", r"\)")
def _money(value) -> str:
return f"{Decimal(str(value or 0)).quantize(Decimal('0.01')):,.2f}"
def _num(value) -> str:
return f"{Decimal(str(value or 0)):,.2f}"
# Ancho aprox de una cadena en Helvetica (para alinear a la derecha / truncar)
def _text_w(s: str, size: float, bold: bool = False) -> float:
return len(s) * size * (0.56 if bold else 0.52)
def _fit(s: str, size: float, max_w: float) -> str:
s = s or ""
if _text_w(s, size) <= max_w:
return s
while s and _text_w(s + "…", size) > max_w:
s = s[:-1]
return s + "…"
def _wrap(text: str, width_chars: int) -> list[str]:
words = (text or "").split()
if not words:
return []
out, cur = [], ""
for w in words:
cand = f"{cur} {w}".strip()
if len(cand) > width_chars and cur:
out.append(cur)
cur = w
else:
cur = cand
if cur:
out.append(cur)
return out
def _hex_rgb(hexs: str | None) -> tuple[float, float, float]:
try:
h = (hexs or "#12294c").lstrip("#")
return tuple(int(h[i : i + 2], 16) / 255 for i in (0, 2, 4)) # type: ignore[return-value]
except Exception:
return (0.07, 0.16, 0.30)
def _prep_logo(logo_bytes: bytes | None):
if not logo_bytes:
return None
try:
from PIL import Image
im = Image.open(io.BytesIO(logo_bytes)).convert("RGB")
im.thumbnail((600, 300))
buf = io.BytesIO()
im.save(buf, format="JPEG", quality=88)
return buf.getvalue(), im.width, im.height
except Exception:
return None
class _Canvas:
"""Acumula operadores de contenido con paginación simple."""
def __init__(self):
self.pages: list[list[str]] = [[]]
self.y = _H
@property
def ops(self) -> list[str]:
return self.pages[-1]
def new_page(self):
self.pages.append([])
self.y = _H - 50
def ensure(self, needed: float):
if self.y - needed < 50:
self.new_page()
def rect(self, x, y, w, h, rgb):
r, g, b = rgb
self.ops.append(f"{r:.3f} {g:.3f} {b:.3f} rg {x:.1f} {y:.1f} {w:.1f} {h:.1f} re f")
def line(self, x1, y1, x2, y2, rgb, width=0.6):
r, g, b = rgb
self.ops.append(f"{width} w {r:.3f} {g:.3f} {b:.3f} RG {x1:.1f} {y1:.1f} m {x2:.1f} {y2:.1f} l S")
def text(self, x, y, s, size=10, rgb=(0, 0, 0), bold=False, right=False):
font = "F2" if bold else "F1"
r, g, b = rgb
tx = x - _text_w(str(s), size, bold) if right else x
self.ops.append(f"BT /{font} {size} Tf {r:.3f} {g:.3f} {b:.3f} rg 1 0 0 1 {tx:.1f} {y:.1f} Tm ({_esc(s)}) Tj ET")
def build_quote_pdf(
*,
emitter: dict,
head: dict,
client: dict,
cargo: list[tuple[str, str]],
route: list[tuple[str, str]],
items: list[dict],
currency: str,
subtotal,
terms: str | None,
footer: str | None,
logo_bytes: bytes | None = None,
accent: str | None = "#12294c",
) -> bytes:
ACC = _hex_rgb(accent)
INK = (0.10, 0.15, 0.24)
GRAY = (0.42, 0.47, 0.55)
LINE = (0.80, 0.84, 0.90)
ZEBRA = (0.955, 0.965, 0.980)
logo = _prep_logo(logo_bytes)
c = _Canvas()
# ---------------- Encabezado ----------------
c.rect(0, _H - 12, _W, 12, ACC) # banda superior
logo_bottom = _H - 95
if logo:
_, lw, lh = logo
dw, dh = 150.0, 150.0 * lh / lw
if dh > 55:
dh, dw = 55.0, 55.0 * lw / lh
c.ops.append(f"q {dw:.1f} 0 0 {dh:.1f} {_ML} {logo_bottom:.1f} cm /Im0 Do Q")
else:
c.text(_ML, _H - 55, emitter.get("name") or "Emisor", 16, INK, bold=True)
# Emisor (derecha)
ex, ey = 320, _H - 42
c.text(ex, ey, emitter.get("name") or "Emisor", 12, INK, bold=True)
ey -= 14
em_lines = []
if emitter.get("rfc"):
em_lines.append(f"RFC: {emitter['rfc']}")
for a in (emitter.get("address") or "").splitlines():
if a.strip():
em_lines.append(a.strip())
contact = " ".join([x for x in [emitter.get("phone"), emitter.get("email"), emitter.get("website")] if x])
if contact:
em_lines.append(contact)
for ln in em_lines[:5]:
c.text(ex, ey, _fit(ln, 8.5, _MR - ex), 8.5, GRAY)
ey -= 11
# Título + regla
c.text(_ML, _H - 150, "COTIZACIÓN", 26, INK, bold=True)
c.line(_ML, _H - 158, _ML + 190, _H - 158, ACC, 2)
# Panel de datos (derecha)
px, pw = 320, _MR - 320
py_top = _H - 128
ph = 74
c.rect(px, py_top - ph, pw, ph, ZEBRA)
c.line(px, py_top, px, py_top - ph, LINE)
hy = py_top - 15
info = [
("No.", head.get("reference") or "-"),
("Fecha", head.get("issue_date") or "-"),
("Vigencia", head.get("valid_until") or "-"),
("Ejecutivo", head.get("owner") or "-"),
("Estatus", str(head.get("status") or "-").capitalize()),
]
for k, v in info:
c.text(px + 10, hy, f"{k}:", 8.5, GRAY, bold=True)
c.text(px + 66, hy, _fit(str(v), 9, pw - 76), 9, INK)
hy -= 12.5
c.y = _H - 215
# ---------------- Helpers de sección ----------------
def section(title: str):
c.ensure(30)
c.rect(_ML, c.y - 18, _MR - _ML, 18, ACC)
c.text(_ML + 8, c.y - 13, title.upper(), 9.5, (1, 1, 1), bold=True)
c.y -= 26
def kv_block(pairs: list[tuple[str, str]]):
rows = [(k, v) for k, v in pairs if v not in (None, "", "None")]
if not rows:
return False
col_w = (_MR - _ML) / 2
i = 0
while i < len(rows):
c.ensure(16)
for col in range(2):
if i + col < len(rows):
k, v = rows[i + col]
x = _ML + 6 + col * col_w
c.text(x, c.y - 11, f"{k}:", 9, GRAY, bold=True)
c.text(x + _text_w(f"{k}: ", 9, True), c.y - 11, _fit(str(v), 9, col_w - 90), 9, INK)
c.y -= 16
i += 2
c.y -= 4
return True
# ---------------- Cliente ----------------
section("Cliente")
if not kv_block([
("Cliente", client.get("name")), ("RFC", client.get("rfc")),
("Correo", client.get("email")), ("Teléfono", client.get("phone")),
]):
c.text(_ML + 6, c.y - 11, "—", 9, GRAY)
c.y -= 16
# ---------------- Carga / Ruta (solo si hay datos) ----------------
if [v for _, v in cargo if v not in (None, "", "None")]:
section("Información de la carga")
kv_block(cargo)
if [v for _, v in route if v not in (None, "", "None")]:
section("Ruta logística")
kv_block(route)
# ---------------- Costos ----------------
section("Costos cotizados")
x_con, x_cant, x_tar, x_imp = _ML, 372, 460, _MR - 6
row_h = 18
# encabezado de tabla
c.ensure(row_h)
c.rect(_ML, c.y - row_h, _MR - _ML, row_h, ACC)
c.text(x_con + 6, c.y - 13, "Concepto", 9, (1, 1, 1), bold=True)
c.text(x_cant, c.y - 13, "Cant.", 9, (1, 1, 1), bold=True, right=True)
c.text(x_tar, c.y - 13, "Tarifa", 9, (1, 1, 1), bold=True, right=True)
c.text(x_imp, c.y - 13, "Importe", 9, (1, 1, 1), bold=True, right=True)
c.y -= row_h
z = False
for it in items:
code = str(it.get("concept") or "")
label = CONCEPT_LABELS.get(code, code)
desc = str(it.get("description") or "")
if desc:
label = f"{label} - {desc}"
qty = Decimal(str(it.get("quantity") or 0))
unit = Decimal(str(it.get("unit_sale") or 0))
amount = (qty * unit).quantize(Decimal("0.01"))
c.ensure(row_h)
if z:
c.rect(_ML, c.y - row_h, _MR - _ML, row_h, ZEBRA)
c.text(x_con + 6, c.y - 13, _fit(label, 9, x_cant - x_con - 40), 9, INK)
c.text(x_cant, c.y - 13, _num(qty), 9, INK, right=True)
c.text(x_tar, c.y - 13, _money(unit), 9, INK, right=True)
c.text(x_imp, c.y - 13, _money(amount), 9, INK, right=True)
c.y -= row_h
z = not z
if not items:
c.text(_ML + 6, c.y - 13, "Sin conceptos.", 9, GRAY)
c.y -= row_h
# borde de la tabla
c.line(_ML, c.y, _MR, c.y, LINE)
c.y -= 12
# ---------------- Totales (caja derecha) ----------------
tb_x, tb_w = 360, _MR - 360
c.ensure(58)
c.rect(tb_x, c.y - 58, tb_w, 58, ZEBRA)
c.line(tb_x, c.y, tb_x, c.y - 58, LINE)
ty = c.y - 16
c.text(tb_x + 10, ty, "Subtotal", 9.5, GRAY, bold=True)
c.text(_MR - 8, ty, f"{currency} {_money(subtotal)}", 9.5, INK, right=True)
ty -= 15
c.text(tb_x + 10, ty, "IVA", 9.5, GRAY, bold=True)
c.text(_MR - 8, ty, "según aplique", 9, GRAY, right=True)
ty -= 6
c.rect(tb_x, ty - 20, tb_w, 20, ACC)
c.text(tb_x + 10, ty - 14, "TOTAL", 10, (1, 1, 1), bold=True)
c.text(_MR - 8, ty - 14, f"{currency} {_money(subtotal)} + IVA", 10, (1, 1, 1), bold=True, right=True)
c.y -= 70
# ---------------- Condiciones ----------------
if terms:
section("Condiciones comerciales")
for para in terms.splitlines():
for ln in (_wrap(para, 108) or [""]):
c.ensure(13)
c.text(_ML + 6, c.y - 10, ln, 8.8, GRAY)
c.y -= 12
c.y -= 4
# pie en todas las páginas
for ops in c.pages:
if footer:
r, g, b = GRAY
ops.append(f"BT /F1 8 Tf {r:.3f} {g:.3f} {b:.3f} rg 1 0 0 1 {_ML} 34 Tm ({_esc(_fit(footer, 8, _MR - _ML))}) Tj ET")
ops.append(f"{ACC[0]:.3f} {ACC[1]:.3f} {ACC[2]:.3f} rg 0 0 {_W} 6 re f")
# ---------------- Ensamblado ----------------
streams = ["\n".join(ops).encode("latin-1", "replace") for ops in c.pages]
objects: list[bytes] = []
def add(obj: bytes):
objects.append(obj)
n_pages = len(c.pages)
has_img = 1 if logo else 0
# numeración: 1 catalog, 2 pages, 3 F1, 4 F2, [5 img], luego páginas y streams
img_num = 5 if has_img else None
base = 6 if has_img else 5
page_nums = list(range(base, base + n_pages))
content_nums = list(range(base + n_pages, base + 2 * n_pages))
kids = " ".join(f"{n} 0 R" for n in page_nums)
add(b"<< /Type /Catalog /Pages 2 0 R >>")
add(f"<< /Type /Pages /Kids [{kids}] /Count {n_pages} >>".encode("latin-1"))
add(b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica /Encoding /WinAnsiEncoding >>")
add(b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica-Bold /Encoding /WinAnsiEncoding >>")
if logo:
jpeg, lw, lh = logo
add(
(
f"<< /Type /XObject /Subtype /Image /Width {lw} /Height {lh} "
f"/ColorSpace /DeviceRGB /BitsPerComponent 8 /Filter /DCTDecode /Length {len(jpeg)} >>\n"
).encode("latin-1") + b"stream\n" + jpeg + b"\nendstream"
)
for i in range(n_pages):
res = "/Font << /F1 3 0 R /F2 4 0 R >>"
if has_img and i == 0:
res += f" /XObject << /Im0 {img_num} 0 R >>"
add(
(
f"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 {_W} {_H}] "
f"/Resources << {res} >> /Contents {content_nums[i]} 0 R >>"
).encode("latin-1")
)
for stream in streams:
add(b"<< /Length " + str(len(stream)).encode() + b" >>\nstream\n" + stream + b"\nendstream")
out = bytearray(b"%PDF-1.4\n%\xe2\xe3\xcf\xd3\n")
offsets = []
for i, obj in enumerate(objects, start=1):
offsets.append(len(out))
out += f"{i} 0 obj\n".encode("latin-1") + obj + b"\nendobj\n"
xref_pos = len(out)
total = len(objects) + 1
out += f"xref\n0 {total}\n".encode("latin-1") + b"0000000000 65535 f \n"
for off in offsets:
out += f"{off:010d} 00000 n \n".encode("latin-1")
out += f"trailer\n<< /Size {total} /Root 1 0 R >>\nstartxref\n{xref_pos}\n%%EOF".encode("latin-1")
return bytes(out)

250
backend/api/v1/modules/crm/quotes/pdf_service.py Normal file
View File

@@ -0,0 +1,250 @@
"""PDF de cotización, configuración de marca por tenant y envío por correo."""
from __future__ import annotations
import logging
from datetime import datetime, timezone
from fastapi import HTTPException, status
from sqlalchemy import text
from sqlalchemy.orm import Session
from ..accounts.models import Account
from ..service_requests.models import ServiceRequest
from .models import Quote, QuoteItem, QuoteSettings
from .pdf import build_quote_pdf
from .service import get_quote
logger = logging.getLogger(__name__)
DEFAULT_TERMS = (
"Tarifas sujetas a disponibilidad de espacio.\n"
"Cualquier variación en peso o volumen generará ajuste tarifario.\n"
"No incluye cargos extraordinarios, maniobras especiales o servicios no especificados.\n"
"Tarifas sujetas a revisión por parte de la línea transportista y autoridades correspondientes."
)
# ---------------- Configuración de marca ----------------
def get_settings(db: Session, tenant_id: int, company_id: int) -> QuoteSettings | None:
return (
db.query(QuoteSettings)
.filter(QuoteSettings.tenant_id == tenant_id, QuoteSettings.company_id == company_id,
QuoteSettings.deleted_at.is_(None))
.first()
)
def upsert_settings(db: Session, tenant_id: int, company_id: int, data: dict) -> QuoteSettings:
obj = get_settings(db, tenant_id, company_id)
if obj is None:
obj = QuoteSettings(tenant_id=tenant_id, company_id=company_id)
db.add(obj)
for field, value in data.items():
if value is not None:
setattr(obj, field, value)
db.commit()
db.refresh(obj)
return obj
def set_logo_key(db: Session, tenant_id: int, company_id: int, file_key: str) -> QuoteSettings:
obj = get_settings(db, tenant_id, company_id)
if obj is None:
obj = QuoteSettings(tenant_id=tenant_id, company_id=company_id)
db.add(obj)
obj.logo_file_key = file_key
db.commit()
db.refresh(obj)
return obj
def _compose_place(city: str | None, country: str | None, port: str | None) -> str | None:
"""Arma 'Ciudad, PAÍS (Puerto)' con las partes que existan (ruta estructurada)."""
head = ", ".join(p for p in (city, country) if p)
if port:
head = f"{head} ({port})" if head else port
return head or None
def _company_row(db: Session, company_id: int) -> dict:
try:
row = db.execute(
text("SELECT name, rfc, logo FROM a76.company WHERE id = :c"), {"c": company_id}
).first()
if row:
return {"name": row[0], "rfc": row[1], "logo": row[2]}
except Exception:
pass
return {}
# ---------------- Construcción del PDF ----------------
def build_pdf_bytes(db: Session, quote: Quote, tenant_id: int, company_id: int) -> bytes:
items = (
db.query(QuoteItem)
.filter(QuoteItem.quote_id == quote.id, QuoteItem.deleted_at.is_(None))
.order_by(QuoteItem.id.asc())
.all()
)
account = (
db.query(Account).filter(Account.id == quote.account_id).first() if quote.account_id else None
)
sr = (
db.query(ServiceRequest).filter(ServiceRequest.id == quote.service_request_id).first()
if quote.service_request_id else None
)
settings = get_settings(db, tenant_id, company_id)
company = _company_row(db, company_id)
# Emisor: config del tenant con respaldo en a76.company
emitter = {
"name": (settings.emitter_name if settings else None) or company.get("name") or "Emisor",
"rfc": (settings.emitter_rfc if settings else None) or company.get("rfc"),
"address": settings.emitter_address if settings else None,
"phone": settings.emitter_phone if settings else None,
"email": settings.emitter_email if settings else None,
"website": settings.emitter_website if settings else None,
}
accent = (settings.accent_color if settings else None) or "#12294c"
prefix = (settings.quote_prefix if settings else None) or "COT"
terms = quote.terms or (settings.default_terms if settings else None) or DEFAULT_TERMS
footer = settings.footer_note if settings else None
# Logo (MinIO)
logo_bytes = None
logo_key = settings.logo_file_key if settings else None
if logo_key:
try:
from core.storage_s3 import get_object_bytes
logo_bytes = get_object_bytes(logo_key)
except Exception as exc:
logger.warning("No se pudo leer el logo del tarifario: %s", exc)
reference = quote.reference or f"{prefix}-{datetime.now().strftime('%Y%m%d')}-{quote.id:03d}"
head = {
"reference": reference,
"issue_date": quote.issue_date.isoformat() if quote.issue_date else None,
"valid_until": quote.valid_until.isoformat() if quote.valid_until else None,
"owner": quote.owner_user_id or "-",
"status": quote.status,
}
client = {
"name": account.name if account else None,
"rfc": account.rfc if account else None,
"email": account.email if account else None,
"phone": account.phone if account else None,
}
cargo = []
route = []
if sr:
cargo = [
("Tipo de mercancía", sr.cargo_type), ("Descripción", sr.commodity),
("Peso", str(sr.weight) if sr.weight is not None else None),
("Volumen", str(sr.volume) if sr.volume is not None else None),
("Tipo de carga", sr.load_type), ("Equipo", sr.container_equipment),
]
route = [
("Operación", sr.operation_type), ("Modo", sr.transport_mode),
("Servicio", sr.service_type), ("Incoterm", sr.incoterm),
("Origen", sr.origin or _compose_place(sr.origin_city, sr.origin_country, sr.origin_port)),
("Destino", sr.destination or _compose_place(sr.destination_city, sr.destination_country, sr.destination_port)),
("Fecha requerida", sr.required_date.isoformat() if sr.required_date else None),
]
return build_quote_pdf(
emitter=emitter, head=head, client=client, cargo=cargo, route=route,
items=[{"concept": i.concept, "description": i.description, "quantity": i.quantity, "unit_sale": i.unit_sale} for i in items],
currency=quote.currency, subtotal=quote.total_sale, terms=terms, footer=footer,
logo_bytes=logo_bytes, accent=accent,
)
def _store_pdf(db: Session, quote: Quote, tenant_id: int, company_id: int, pdf_bytes: bytes) -> str:
from core.storage_s3 import put_object_bytes
ref = (quote.reference or f"cot-{quote.id}").replace("/", "-")
key = f"tenants/{tenant_id}/companies/{company_id}/crm-quotes/{quote.id}/cotizacion-{ref}.pdf"
put_object_bytes(key, pdf_bytes, content_type="application/pdf")
quote.pdf_file_key = key
db.commit()
return key
def get_pdf_url(db: Session, quote_id: int, tenant_id: int, company_id: int) -> str:
from core.storage_s3 import presigned_get_url
quote = get_quote(db, quote_id, tenant_id, company_id)
pdf_bytes = build_pdf_bytes(db, quote, tenant_id, company_id)
key = _store_pdf(db, quote, tenant_id, company_id, pdf_bytes)
return presigned_get_url(key)
# ---------------- Envío por correo ----------------
async def send_quote_email(
db: Session, quote_id: int, tenant_id: int, company_id: int,
to: str | None, subject: str | None, message: str | None,
) -> dict:
import ssl
from email import encoders
from email.mime.base import MIMEBase
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
import aiosmtplib
from core.config import settings as cfg
quote = get_quote(db, quote_id, tenant_id, company_id)
account = db.query(Account).filter(Account.id == quote.account_id).first() if quote.account_id else None
recipient = to or (account.email if account else None)
if not recipient:
raise HTTPException(status_code=400, detail="No hay correo destino (captura uno o pon el correo del cliente).")
pdf_bytes = build_pdf_bytes(db, quote, tenant_id, company_id)
_store_pdf(db, quote, tenant_id, company_id, pdf_bytes)
ref = quote.reference or f"COT-{quote.id}"
msg = MIMEMultipart()
msg["From"] = f"{cfg.SMTP_FROM_NAME} <{cfg.SMTP_USER}>"
msg["To"] = recipient
msg["Subject"] = subject or f"Cotización {ref}"
html = (
"<div style='font-family:Arial,sans-serif;color:#333;max-width:600px'>"
f"<p>{(message or 'Adjunto la cotización solicitada. Quedamos atentos.').replace(chr(10), '<br>')}</p>"
f"<p style='color:#6b7280;font-size:12px'>Cotización {ref}</p></div>"
)
msg.attach(MIMEText(html, "html"))
part = MIMEBase("application", "pdf")
part.set_payload(pdf_bytes)
encoders.encode_base64(part)
part.add_header("Content-Disposition", f'attachment; filename="cotizacion-{ref}.pdf"')
msg.attach(part)
if not (cfg.SMTP_USER and cfg.SMTP_PASSWORD):
raise HTTPException(status_code=503, detail="El correo saliente (SMTP) no está configurado en el servidor.")
ctx = ssl.create_default_context()
ctx.check_hostname = False
ctx.verify_mode = ssl.CERT_NONE
try:
# Puerto 465 = SSL implícito; los demás (587/2525/…) = STARTTLS.
await aiosmtplib.send(
msg,
hostname=cfg.SMTP_HOST,
port=cfg.SMTP_PORT,
username=cfg.SMTP_USER,
password=cfg.SMTP_PASSWORD,
use_tls=(cfg.SMTP_PORT == 465),
start_tls=(cfg.SMTP_PORT != 465),
tls_context=ctx,
validate_certs=False,
timeout=30,
)
except Exception as exc:
logger.error("Error enviando cotización %s: %s", quote_id, exc)
raise HTTPException(status_code=502, detail=f"No se pudo enviar el correo: {exc}")
# Marca como enviada
if quote.status == "borrador":
quote.status = "enviada"
quote.sent_at = datetime.now(timezone.utc)
db.commit()
return {"sent_to": recipient, "reference": ref}

109
backend/api/v1/modules/crm/quotes/routes.py
View File

@@ -1,22 +1,76 @@
from fastapi import APIRouter, Depends, Query, status
from fastapi import APIRouter, Depends, File, Query, Response, UploadFile, status
from sqlalchemy.orm import Session
from core.database import get_core_db
from core.security import get_current_user
from . import service
from . import pdf_service, service
from .dto import (
QuoteCreate,
QuoteItemCreate,
QuoteItemResponse,
QuoteItemUpdate,
QuoteResponse,
QuoteSettingsInput,
QuoteSettingsResponse,
QuoteUpdate,
SendQuoteEmailRequest,
)
router = APIRouter()
# ----- Configuración de marca del formato de cotización -----
@router.get("/quote-settings", response_model=QuoteSettingsResponse)
def get_quote_settings(
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
obj = pdf_service.get_settings(db, current_user["tenant_id"], company_id)
return obj or QuoteSettingsResponse()
@router.put("/quote-settings", response_model=QuoteSettingsResponse)
def save_quote_settings(
payload: QuoteSettingsInput,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
return pdf_service.upsert_settings(db, current_user["tenant_id"], company_id, payload.model_dump(exclude_unset=True))
@router.post("/quote-settings/logo", response_model=QuoteSettingsResponse)
async def upload_quote_logo(
company_id: int = Query(...),
file: UploadFile = File(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
from core.storage_s3 import put_object_bytes
tenant_id = current_user["tenant_id"]
content = await file.read()
safe = (file.filename or "logo").replace("/", "-")
key = f"tenants/{tenant_id}/companies/{company_id}/crm-quote-logo/{safe}"
put_object_bytes(key, content, content_type=file.content_type or "image/png")
return pdf_service.set_logo_key(db, tenant_id, company_id, key)
@router.get("/quote-settings/logo-url")
def get_logo_url(
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
from core.storage_s3 import presigned_get_url
obj = pdf_service.get_settings(db, current_user["tenant_id"], company_id)
if not obj or not obj.logo_file_key:
return {"url": None}
return {"url": presigned_get_url(obj.logo_file_key)}
def _user_id(current_user: dict) -> str | None:
return current_user.get("sub") or current_user.get("id")
@@ -56,6 +110,24 @@ def create_quote(
return service.create_quote(db, payload, tenant_id, company_id, _user_id(current_user))
@router.post(
"/quotes/from-service-request",
response_model=list[QuoteResponse],
status_code=status.HTTP_201_CREATED,
)
def create_quotes_from_service_request(
service_request_id: int = Query(..., description="Solicitud de servicio a cotizar"),
company_id: int = Query(..., description="Company ID"),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Genera la(s) cotización(es) desde una solicitud. Si es 'Ambas' devuelve 2 (FCL/LCL)."""
tenant_id = current_user["tenant_id"]
return service.create_quotes_from_service_request(
db, service_request_id, tenant_id, company_id, _user_id(current_user)
)
@router.patch("/quotes/{quote_id}", response_model=QuoteResponse)
def update_quote(
quote_id: int,
@@ -98,6 +170,39 @@ def reject_quote(
return service.reject_quote(db, quote_id, current_user["tenant_id"], company_id)
@router.get("/quotes/{quote_id}/pdf")
def quote_pdf(
quote_id: int,
company_id: int = Query(..., description="Company ID"),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Devuelve el PDF de la cotización directamente (vía backend, sin exponer MinIO)."""
tenant_id = current_user["tenant_id"]
quote = service.get_quote(db, quote_id, tenant_id, company_id)
pdf_bytes = pdf_service.build_pdf_bytes(db, quote, tenant_id, company_id)
ref = (quote.reference or f"cot-{quote.id}").replace("/", "-")
return Response(
content=pdf_bytes,
media_type="application/pdf",
headers={"Content-Disposition": f'inline; filename="cotizacion-{ref}.pdf"'},
)
@router.post("/quotes/{quote_id}/send-email")
async def quote_send_email(
quote_id: int,
payload: SendQuoteEmailRequest,
company_id: int = Query(..., description="Company ID"),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Genera el PDF y lo envía por correo (al cliente o al destinatario indicado)."""
return await pdf_service.send_quote_email(
db, quote_id, current_user["tenant_id"], company_id, payload.to, payload.subject, payload.message
)
@router.post("/quotes/{quote_id}/clone", response_model=QuoteResponse, status_code=status.HTTP_201_CREATED)
def clone_quote(
quote_id: int,

145
backend/api/v1/modules/crm/quotes/service.py
View File

@@ -1,4 +1,4 @@
from datetime import datetime, timezone
from datetime import date, datetime, timezone
from decimal import Decimal
from fastapi import HTTPException, status
@@ -6,7 +6,11 @@ from sqlalchemy import func
from sqlalchemy.orm import Session
from ..accounts.models import Account
from ..service_requests.models import ServiceRequest
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
from ..service_requests.models import RateRequest, ServiceRequest
from ..suppliers.models import Supplier
from .dto import QuoteCreate, QuoteItemCreate, QuoteItemUpdate, QuoteUpdate
from .models import Quote, QuoteItem
@@ -70,7 +74,18 @@ def get_quotes(
query = query.filter(Quote.account_id == account_id)
if search:
query = query.filter(Quote.reference.ilike(f"%{search}%"))
return query.order_by(Quote.created_at.desc()).all()
quotes = query.order_by(Quote.created_at.desc()).all()
# Enriquecer con el folio de la solicitud referenciada (para verlo en la lista)
sr_ids = {q.service_request_id for q in quotes if q.service_request_id}
if sr_ids:
refs = dict(
db.query(ServiceRequest.id, ServiceRequest.reference)
.filter(ServiceRequest.id.in_(sr_ids))
.all()
)
for q in quotes:
q.service_request_reference = refs.get(q.service_request_id)
return quotes
def get_quote(db: Session, quote_id: int, tenant_id: int, company_id: int) -> Quote:
@@ -89,18 +104,142 @@ def get_quote(db: Session, quote_id: int, tenant_id: int, company_id: int) -> Qu
return obj
def _sr_direction(db: Session, service_request_id: int | None) -> str | None:
"""Dirección impo/expo heredada de la solicitud asociada (para el folio)."""
if not service_request_id:
return None
sr = db.query(ServiceRequest).filter(ServiceRequest.id == service_request_id).first()
return sr.operation_type if sr else None
def create_quote(
db: Session, payload: QuoteCreate, tenant_id: int, company_id: int, user_id: str | None = None
) -> Quote:
data = payload.model_dump()
_validate_refs(db, data, tenant_id, company_id)
obj = Quote(**data, tenant_id=tenant_id, company_id=company_id, created_by=user_id, updated_by=user_id)
# Fecha de la cotización: por defecto hoy si no se capturó
if obj.issue_date is None:
obj.issue_date = date.today()
# 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)
return obj
def create_quotes_from_service_request(
db: Session, service_request_id: int, tenant_id: int, company_id: int, user_id: str | None = None
) -> list[Quote]:
"""Genera cotización(es) a partir de una solicitud de servicio.
Si la solicitud es "Ambas" (FCL y LCL), genera **dos** cotizaciones (una por
variante) para comparar. Cada cotización toma su propio folio C... y hereda la
dirección impo/expo de la solicitud. Los conceptos se siembran desde las
solicitudes de tarifa (RateRequest) capturadas en la solicitud.
"""
sr = (
db.query(ServiceRequest)
.filter(
ServiceRequest.id == service_request_id,
ServiceRequest.tenant_id == tenant_id,
ServiceRequest.company_id == company_id,
ServiceRequest.deleted_at.is_(None),
)
.first()
)
if not sr:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Solicitud no encontrada")
variants = ["FCL", "LCL"] if (sr.load_type or "").upper() == "AMBAS" else [sr.load_type or None]
rate_requests = (
db.query(RateRequest)
.filter(
RateRequest.service_request_id == sr.id,
RateRequest.tenant_id == tenant_id,
RateRequest.company_id == company_id,
RateRequest.deleted_at.is_(None),
)
.all()
)
# Etiquetas legibles de los servicios adicionales (global + tenant) para los conceptos
service_labels = {
code: label
for code, label in db.query(CatalogItem.code, CatalogItem.label).filter(
CatalogItem.catalog == "servicio_adicional"
)
}
service_costs = sr.additional_service_costs or {}
created: list[Quote] = []
for variant in variants:
quote = Quote(
account_id=sr.account_id,
service_request_id=sr.id,
currency=sr.currency or "USD",
load_type=variant,
status="borrador",
issue_date=date.today(),
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,
updated_by=user_id,
)
db.add(quote)
db.flush()
for rr in rate_requests:
amount = rr.rate_amount if rr.rate_amount is not None else Decimal(0)
db.add(QuoteItem(
quote_id=quote.id, concept=rr.concept, description=rr.description,
supplier_id=rr.supplier_id, quantity=Decimal(1),
unit_cost=amount, unit_sale=amount, currency=rr.currency,
tenant_id=tenant_id, company_id=company_id,
))
# Servicios adicionales marcados en la solicitud → conceptos con su costo estimado
for code in (sr.additional_services or []):
amount = Decimal(str(service_costs.get(code) or 0))
db.add(QuoteItem(
quote_id=quote.id, concept=code[:60],
description=service_labels.get(code, "Servicio adicional"),
quantity=Decimal(1), unit_cost=amount, unit_sale=amount,
currency=sr.currency, tenant_id=tenant_id, company_id=company_id,
))
# Carga aérea: concepto de flete con el peso a cobrar (P/Vol) como cantidad,
# para que el ejecutivo capture la tarifa por kg.
if (variant or "").upper() == "AEREO":
chargeable = air_chargeable_kg(
sr.weight, sr.length_cm, sr.width_cm, sr.height_cm,
sr.pallets_count or sr.pieces_count or 1,
)
db.add(QuoteItem(
quote_id=quote.id, concept="flete_internacional",
description=f"Flete aéreo — peso a cobrar {chargeable.quantize(Decimal('0.01'))} kg (P/Vol)",
quantity=chargeable, unit_cost=Decimal(0), unit_sale=Decimal(0),
currency=sr.currency, tenant_id=tenant_id, company_id=company_id,
))
db.flush()
_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)
return created
def update_quote(
db: Session, quote_id: int, payload: QuoteUpdate, tenant_id: int, company_id: int, user_id: str | None = None
) -> Quote:

0
backend/api/v1/modules/crm/rates/__init__.py Normal file
View File

178
backend/api/v1/modules/crm/rates/dto.py Normal file
View File

@@ -0,0 +1,178 @@
"""Schemas del módulo Tarifario."""
from datetime import date, datetime
from decimal import Decimal
from pydantic import BaseModel, ConfigDict, Field
# ---------- Quiebres y cargos ----------
class RateBreakDTO(BaseModel):
model_config = ConfigDict(from_attributes=True)
from_qty: Decimal = Field(0)
rate: Decimal = Field(0)
class RateChargeDTO(BaseModel):
model_config = ConfigDict(from_attributes=True)
concept: str = Field(..., max_length=60)
charge_type: str = Field("fijo", max_length=20)
value: Decimal | None = None
condition: str | None = None
class RateChargeCreate(BaseModel):
concept: str = Field(..., max_length=60)
charge_type: str = Field("fijo", max_length=20)
value: Decimal | None = None
condition: str | None = None
rate_lane_id: int | None = None
class RateChargeUpdate(BaseModel):
concept: str | None = Field(None, max_length=60)
charge_type: str | None = Field(None, max_length=20)
value: Decimal | None = None
condition: str | None = None
class RateChargeResponse(BaseModel):
model_config = ConfigDict(from_attributes=True)
id: int
rate_sheet_id: int | None
rate_lane_id: int | None
concept: str
charge_type: str
value: Decimal | None
condition: str | None
# ---------- Rutas ----------
class RateLaneBase(BaseModel):
origin: str | None = Field(None, max_length=20)
destination: str | None = Field(None, max_length=20)
region: str | None = Field(None, max_length=60)
equipment_type: str | None = Field(None, max_length=20)
rate_unit: str | None = Field(None, max_length=20)
min_charge: Decimal | None = None
flat_rate: Decimal | None = None
transit_days: int | None = None
notes: str | None = None
class RateLaneCreate(RateLaneBase):
breaks: list[RateBreakDTO] = Field(default_factory=list)
class RateLaneUpdate(RateLaneBase):
breaks: list[RateBreakDTO] | None = None
class RateLaneResponse(RateLaneBase):
model_config = ConfigDict(from_attributes=True)
id: int
rate_sheet_id: int
breaks: list[RateBreakDTO] = Field(default_factory=list)
# ---------- Tarifario (cabecera) ----------
class RateSheetBase(BaseModel):
supplier_id: int | None = None
mode: str = Field(..., max_length=20)
name: str = Field(..., min_length=1, max_length=255)
currency: str | None = Field("USD", max_length=3)
valid_from: date | None = None
valid_to: date | None = None
default_origin: str | None = Field(None, max_length=20)
status: str = Field("borrador", max_length=20)
notes: str | None = None
class RateSheetCreate(RateSheetBase):
pass
class RateSheetUpdate(BaseModel):
supplier_id: int | None = None
mode: str | None = Field(None, max_length=20)
name: str | None = Field(None, max_length=255)
currency: str | None = Field(None, max_length=3)
valid_from: date | None = None
valid_to: date | None = None
default_origin: str | None = Field(None, max_length=20)
status: str | None = Field(None, max_length=20)
notes: str | None = None
class RateSheetResponse(RateSheetBase):
model_config = ConfigDict(from_attributes=True)
id: int
tenant_id: int
company_id: int
source_file: str | None = None
created_by: str | None = None
updated_by: str | None = None
created_at: datetime
updated_at: datetime
lane_count: int | None = None
# ---------- Importación ----------
class ImportPreviewRow(BaseModel):
row: int
data: dict
ok: bool
warnings: list[str] = Field(default_factory=list)
errors: list[str] = Field(default_factory=list)
class ImportPreview(BaseModel):
mode: str
total: int
valid: int
rows: list[ImportPreviewRow]
columns: list[str]
class ImportConfirm(RateSheetCreate):
lanes: list[RateLaneCreate]
# ---------- Costeo ----------
class CostRequest(BaseModel):
mode: str
origin: str | None = None
destination: str | None = None
on_date: date | None = None
gross_weight_kg: Decimal | None = None
volume_m3: Decimal | None = None
# Dimensiones (cm) para el peso volumétrico aéreo (P/Vol = L×A×H×cant / 6000)
length_cm: Decimal | None = None
width_cm: Decimal | None = None
height_cm: Decimal | None = None
equipment_type: str | None = None
quantity: int = 1
dangerous: bool = False
class CostChargeLine(BaseModel):
concept: str
amount: Decimal
class CostOption(BaseModel):
rate_sheet_id: int
rate_sheet_name: str
supplier_id: int | None
currency: str | None
chargeable: Decimal | None = None # peso/wm facturable usado
base_cost: Decimal
charges: list[CostChargeLine] = Field(default_factory=list)
total_cost: Decimal
transit_days: int | None = None
detail: str | None = None
class CostResult(BaseModel):
request: CostRequest
options: list[CostOption]

93
backend/api/v1/modules/crm/rates/models.py Normal file
View File

@@ -0,0 +1,93 @@
"""Modelos del módulo Tarifario (base de costos para Cotizaciones).
Un ``RateSheet`` (tarifario) pertenece a un proveedor y agrupa muchas
``RateLane`` (rutas origen→destino). Cada ruta tiene, según el modo:
- Aéreo / LCL: varios ``RateBreak`` (quiebres de peso/volumen con su tarifa).
- FCL / terrestre: una tarifa plana por contenedor/unidad (``flat_rate``).
Los ``RateCharge`` son cargos adicionales a nivel tarifario o ruta.
"""
from datetime import date
from decimal import Decimal
from sqlalchemy import Date, ForeignKey, 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
class RateSheet(Base, TenantScopedMixin, TimestampMixin):
__tablename__ = "rate_sheets"
__table_args__ = {"schema": "crm"}
id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
supplier_id: Mapped[int | None] = mapped_column(
Integer, ForeignKey("crm.suppliers.id"), nullable=True, index=True
)
# aereo | maritimo_fcl | maritimo_lcl | terrestre
mode: Mapped[str] = mapped_column(String(20), nullable=False, index=True)
name: Mapped[str] = mapped_column(String(255), nullable=False)
currency: Mapped[str | None] = mapped_column(String(3), nullable=True, server_default=text("'USD'"))
valid_from: Mapped[date | None] = mapped_column(Date, nullable=True)
valid_to: Mapped[date | None] = mapped_column(Date, nullable=True)
default_origin: Mapped[str | None] = mapped_column(String(20), nullable=True)
# borrador | activo | vencido | reemplazado
status: Mapped[str] = mapped_column(String(20), nullable=False, server_default=text("'borrador'"))
source_file: Mapped[str | None] = mapped_column(String(512), nullable=True)
source_url: Mapped[str | None] = mapped_column(String(1024), nullable=True)
notes: Mapped[str | None] = mapped_column(Text, nullable=True)
created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
class RateLane(Base, TenantScopedMixin, TimestampMixin):
__tablename__ = "rate_lanes"
__table_args__ = {"schema": "crm"}
id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
rate_sheet_id: Mapped[int] = mapped_column(
Integer, ForeignKey("crm.rate_sheets.id"), nullable=False, index=True
)
origin: Mapped[str | None] = mapped_column(String(20), nullable=True, index=True)
destination: Mapped[str | None] = mapped_column(String(20), nullable=True, index=True)
region: Mapped[str | None] = mapped_column(String(60), nullable=True)
# Solo FCL/terrestre (código del catálogo tipo_equipo). Nulo en aéreo/LCL.
equipment_type: Mapped[str | None] = mapped_column(String(20), nullable=True)
# per_kg | per_wm | per_container | flat
rate_unit: Mapped[str | None] = mapped_column(String(20), nullable=True)
min_charge: Mapped[Decimal | None] = mapped_column(Numeric(14, 4), nullable=True)
flat_rate: Mapped[Decimal | None] = mapped_column(Numeric(14, 4), nullable=True)
transit_days: Mapped[int | None] = mapped_column(Integer, nullable=True)
notes: Mapped[str | None] = mapped_column(Text, nullable=True)
class RateBreak(Base, TenantScopedMixin, TimestampMixin):
__tablename__ = "rate_breaks"
__table_args__ = {"schema": "crm"}
id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
rate_lane_id: Mapped[int] = mapped_column(
Integer, ForeignKey("crm.rate_lanes.id"), nullable=False, index=True
)
# Umbral del quiebre (kg en aéreo; W/M en LCL)
from_qty: Mapped[Decimal] = mapped_column(Numeric(12, 3), nullable=False, server_default=text("0"))
rate: Mapped[Decimal] = mapped_column(Numeric(14, 4), nullable=False, server_default=text("0"))
class RateCharge(Base, TenantScopedMixin, TimestampMixin):
__tablename__ = "rate_charges"
__table_args__ = {"schema": "crm"}
id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
rate_sheet_id: Mapped[int | None] = mapped_column(
Integer, ForeignKey("crm.rate_sheets.id"), nullable=True, index=True
)
rate_lane_id: Mapped[int | None] = mapped_column(
Integer, ForeignKey("crm.rate_lanes.id"), nullable=True, index=True
)
concept: Mapped[str] = mapped_column(String(60), nullable=False)
# fijo | por_kg | por_guia | por_contenedor | porcentaje
charge_type: Mapped[str] = mapped_column(String(20), nullable=False, server_default=text("'fijo'"))
value: Mapped[Decimal | None] = mapped_column(Numeric(14, 4), nullable=True)
condition: Mapped[str | None] = mapped_column(Text, nullable=True)

269
backend/api/v1/modules/crm/rates/routes.py Normal file
View File

@@ -0,0 +1,269 @@
"""Endpoints del módulo Tarifario."""
from datetime import date
from fastapi import APIRouter, Depends, File, Form, Query, Response, UploadFile, status
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 (
CostRequest,
CostResult,
ImportPreview,
RateBreakDTO,
RateChargeCreate,
RateChargeResponse,
RateChargeUpdate,
RateLaneCreate,
RateLaneResponse,
RateSheetCreate,
RateSheetResponse,
RateSheetUpdate,
)
router = APIRouter(prefix="/rate-sheets", tags=["Tarifario"])
def _ctx(current_user: dict):
return current_user["tenant_id"], current_user.get("sub") or current_user.get("id")
def _sheet_out(db: Session, tenant_id: int, sheet) -> RateSheetResponse:
out = RateSheetResponse.model_validate(sheet)
out.lane_count = service.lane_count(db, tenant_id, sheet.id)
return out
def _lane_out(db: Session, lane) -> RateLaneResponse:
out = RateLaneResponse.model_validate(lane)
out.breaks = [RateBreakDTO.model_validate(b) for b in service.breaks_of(db, lane.id)]
return out
# ---------------- Tarifarios ----------------
@router.get("", response_model=list[RateSheetResponse])
def list_sheets(
company_id: int = Query(...),
mode: str | None = Query(None),
supplier_id: int | None = Query(None),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, _ = _ctx(current_user)
sheets = service.list_sheets(db, tenant_id, company_id, mode=mode, supplier_id=supplier_id)
return [_sheet_out(db, tenant_id, s) for s in sheets]
@router.post("", response_model=RateSheetResponse, status_code=status.HTTP_201_CREATED)
def create_sheet(
data: RateSheetCreate,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, user_id = _ctx(current_user)
sheet = service.create_sheet(db, tenant_id, company_id, data, user_id)
return _sheet_out(db, tenant_id, sheet)
@router.get("/template")
def download_template(
mode: str = Query(..., description="aereo | maritimo_fcl | maritimo_lcl | terrestre"),
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
):
content = service.build_template(mode)
return Response(
content=content,
media_type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
headers={"Content-Disposition": f'attachment; filename="plantilla_tarifario_{mode}.xlsx"'},
)
@router.post("/import/preview", response_model=ImportPreview)
async def import_preview(
company_id: int = Query(...),
mode: str = Form(...),
file: UploadFile = File(...),
current_user: dict = Depends(get_current_user),
):
content = await file.read()
return service.parse_excel(mode, content)
@router.post("/import", response_model=RateSheetResponse, status_code=status.HTTP_201_CREATED)
async def import_sheet(
company_id: int = Query(...),
mode: str = Form(...),
name: str = Form(...),
supplier_id: int | None = Form(None),
currency: str = Form("USD"),
valid_from: date | None = Form(None),
valid_to: date | None = Form(None),
default_origin: str | None = Form(None),
file: UploadFile = File(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, user_id = _ctx(current_user)
content = await file.read()
header = RateSheetCreate(
mode=mode, name=name, supplier_id=supplier_id, currency=currency,
valid_from=valid_from, valid_to=valid_to, default_origin=default_origin,
)
sheet = service.import_from_excel(db, tenant_id, company_id, mode, content, header, user_id)
return _sheet_out(db, tenant_id, sheet)
@router.get("/{sheet_id}", response_model=RateSheetResponse)
def get_sheet(
sheet_id: int,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, _ = _ctx(current_user)
return _sheet_out(db, tenant_id, service.get_sheet(db, tenant_id, company_id, sheet_id))
@router.patch("/{sheet_id}", response_model=RateSheetResponse)
def update_sheet(
sheet_id: int,
data: RateSheetUpdate,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, user_id = _ctx(current_user)
return _sheet_out(db, tenant_id, service.update_sheet(db, tenant_id, company_id, sheet_id, data, user_id))
@router.delete("/{sheet_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_sheet(
sheet_id: int,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, _ = _ctx(current_user)
service.delete_sheet(db, tenant_id, company_id, sheet_id)
# ---------------- Rutas (lanes) ----------------
@router.get("/{sheet_id}/lanes", response_model=list[RateLaneResponse])
def list_lanes(
sheet_id: int,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, _ = _ctx(current_user)
service.get_sheet(db, tenant_id, company_id, sheet_id)
return [_lane_out(db, lane) for lane in service.list_lanes(db, tenant_id, sheet_id)]
@router.post("/{sheet_id}/lanes", response_model=RateLaneResponse, status_code=status.HTTP_201_CREATED)
def create_lane(
sheet_id: int,
data: RateLaneCreate,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, _ = _ctx(current_user)
lane = service.create_lane(db, tenant_id, company_id, sheet_id, data)
return _lane_out(db, lane)
@router.delete("/{sheet_id}/lanes/{lane_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_lane(
sheet_id: int,
lane_id: int,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, _ = _ctx(current_user)
service.delete_lane(db, tenant_id, sheet_id, lane_id)
# ---------------- Cargos adicionales ----------------
@router.get("/{sheet_id}/charges", response_model=list[RateChargeResponse])
def list_charges(
sheet_id: int,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, _ = _ctx(current_user)
service.get_sheet(db, tenant_id, company_id, sheet_id)
return service.list_charges(db, tenant_id, sheet_id)
@router.post("/{sheet_id}/charges", response_model=RateChargeResponse, status_code=status.HTTP_201_CREATED)
def create_charge(
sheet_id: int,
data: RateChargeCreate,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, _ = _ctx(current_user)
return service.create_charge(db, tenant_id, company_id, sheet_id, data)
@router.patch("/{sheet_id}/charges/{charge_id}", response_model=RateChargeResponse)
def update_charge(
sheet_id: int,
charge_id: int,
data: RateChargeUpdate,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, _ = _ctx(current_user)
return service.update_charge(db, tenant_id, sheet_id, charge_id, data)
@router.delete("/{sheet_id}/charges/{charge_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_charge(
sheet_id: int,
charge_id: int,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
tenant_id, _ = _ctx(current_user)
service.delete_charge(db, tenant_id, sheet_id, charge_id)
# ---------------- Motor de costeo ----------------
cost_router = APIRouter(tags=["Tarifario"])
@cost_router.post("/rate-quote", response_model=CostResult)
def rate_quote(
req: CostRequest,
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Calcula opciones de costo (por proveedor) para una ruta/carga."""
tenant_id, _ = _ctx(current_user)
options = service.quote_cost(db, tenant_id, company_id, req)
return CostResult(request=req, options=options)
@cost_router.get("/rate-locations")
def rate_locations(
mode: str = Query(...),
company_id: int = Query(...),
current_user: dict = Depends(get_current_user),
db: Session = Depends(get_core_db),
):
"""Orígenes/destinos cotizables (de los tarifarios activos) para alinear el cotizador."""
tenant_id, _ = _ctx(current_user)
return service.lane_locations(db, tenant_id, company_id, mode)

565
backend/api/v1/modules/crm/rates/service.py Normal file
View File

@@ -0,0 +1,565 @@
"""Lógica del módulo Tarifario: CRUD, importación por Excel y motor de costeo."""
import io
from datetime import date
from decimal import Decimal
from typing import Any
from fastapi import HTTPException, status
from sqlalchemy import and_, or_
from sqlalchemy.orm import Session
from .dto import (
CostChargeLine,
CostOption,
CostRequest,
ImportConfirm,
ImportPreview,
ImportPreviewRow,
RateLaneCreate,
RateSheetCreate,
RateSheetUpdate,
)
from ..common.pricing import air_volumetric_kg
from .models import RateBreak, RateCharge, RateLane, RateSheet
# Factor volumétrico aéreo: 1 m³ = 167 kg (equivale a 6000 cm³/kg).
# Respaldo cuando solo se conoce el volumen en m³ (sin dimensiones cm).
AIR_VOLUMETRIC_FACTOR = Decimal("167")
# ============================================================ CRUD tarifarios
def _sheet_query(db: Session, tenant_id: int, company_id: int):
return db.query(RateSheet).filter(
RateSheet.tenant_id == tenant_id,
RateSheet.company_id == company_id,
RateSheet.deleted_at.is_(None),
)
def list_sheets(db: Session, tenant_id: int, company_id: int, mode: str | None = None,
supplier_id: int | None = None) -> list[RateSheet]:
q = _sheet_query(db, tenant_id, company_id)
if mode:
q = q.filter(RateSheet.mode == mode)
if supplier_id:
q = q.filter(RateSheet.supplier_id == supplier_id)
return q.order_by(RateSheet.created_at.desc()).all()
def lane_count(db: Session, tenant_id: int, sheet_id: int) -> int:
return (
db.query(RateLane)
.filter(RateLane.rate_sheet_id == sheet_id, RateLane.tenant_id == tenant_id,
RateLane.deleted_at.is_(None))
.count()
)
def get_sheet(db: Session, tenant_id: int, company_id: int, sheet_id: int) -> RateSheet:
sheet = _sheet_query(db, tenant_id, company_id).filter(RateSheet.id == sheet_id).first()
if not sheet:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Tarifario no encontrado")
return sheet
def create_sheet(db: Session, tenant_id: int, company_id: int, data: RateSheetCreate,
user_id: str | None) -> RateSheet:
sheet = RateSheet(
tenant_id=tenant_id, company_id=company_id,
**data.model_dump(),
created_by=user_id, updated_by=user_id,
)
db.add(sheet)
db.commit()
db.refresh(sheet)
return sheet
def update_sheet(db: Session, tenant_id: int, company_id: int, sheet_id: int,
data: RateSheetUpdate, user_id: str | None) -> RateSheet:
sheet = get_sheet(db, tenant_id, company_id, sheet_id)
for field, value in data.model_dump(exclude_unset=True).items():
setattr(sheet, field, value)
sheet.updated_by = user_id
db.commit()
db.refresh(sheet)
return sheet
def delete_sheet(db: Session, tenant_id: int, company_id: int, sheet_id: int) -> None:
from sqlalchemy import func
sheet = get_sheet(db, tenant_id, company_id, sheet_id)
sheet.deleted_at = func.now()
db.commit()
# ============================================================ Rutas (lanes)
def list_lanes(db: Session, tenant_id: int, sheet_id: int) -> list[RateLane]:
return (
db.query(RateLane)
.filter(RateLane.rate_sheet_id == sheet_id, RateLane.tenant_id == tenant_id,
RateLane.deleted_at.is_(None))
.order_by(RateLane.region, RateLane.destination)
.all()
)
def breaks_of(db: Session, lane_id: int) -> list[RateBreak]:
return (
db.query(RateBreak)
.filter(RateBreak.rate_lane_id == lane_id, RateBreak.deleted_at.is_(None))
.order_by(RateBreak.from_qty)
.all()
)
def _add_lane(db: Session, tenant_id: int, company_id: int, sheet_id: int,
lane_data: RateLaneCreate) -> RateLane:
payload = lane_data.model_dump(exclude={"breaks"})
lane = RateLane(tenant_id=tenant_id, company_id=company_id, rate_sheet_id=sheet_id, **payload)
db.add(lane)
db.flush() # id
for br in lane_data.breaks:
db.add(RateBreak(
tenant_id=tenant_id, company_id=company_id, rate_lane_id=lane.id,
from_qty=br.from_qty, rate=br.rate,
))
return lane
def create_lane(db: Session, tenant_id: int, company_id: int, sheet_id: int,
lane_data: RateLaneCreate) -> RateLane:
get_sheet(db, tenant_id, company_id, sheet_id) # valida pertenencia
lane = _add_lane(db, tenant_id, company_id, sheet_id, lane_data)
db.commit()
db.refresh(lane)
return lane
def delete_lane(db: Session, tenant_id: int, sheet_id: int, lane_id: int) -> None:
from sqlalchemy import func
lane = (
db.query(RateLane)
.filter(RateLane.id == lane_id, RateLane.rate_sheet_id == sheet_id,
RateLane.tenant_id == tenant_id)
.first()
)
if not lane:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Ruta no encontrada")
lane.deleted_at = func.now()
db.commit()
# ============================================================ Cargos adicionales
def list_charges(db: Session, tenant_id: int, sheet_id: int) -> list[RateCharge]:
return (
db.query(RateCharge)
.filter(RateCharge.rate_sheet_id == sheet_id, RateCharge.tenant_id == tenant_id,
RateCharge.deleted_at.is_(None))
.order_by(RateCharge.concept)
.all()
)
def create_charge(db: Session, tenant_id: int, company_id: int, sheet_id: int, data) -> RateCharge:
get_sheet(db, tenant_id, company_id, sheet_id)
ch = RateCharge(
tenant_id=tenant_id, company_id=company_id, rate_sheet_id=sheet_id,
rate_lane_id=data.rate_lane_id, concept=data.concept, charge_type=data.charge_type,
value=data.value, condition=data.condition,
)
db.add(ch)
db.commit()
db.refresh(ch)
return ch
def update_charge(db: Session, tenant_id: int, sheet_id: int, charge_id: int, data) -> RateCharge:
ch = (
db.query(RateCharge)
.filter(RateCharge.id == charge_id, RateCharge.rate_sheet_id == sheet_id,
RateCharge.tenant_id == tenant_id)
.first()
)
if not ch:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Cargo no encontrado")
for field, value in data.model_dump(exclude_unset=True).items():
setattr(ch, field, value)
db.commit()
db.refresh(ch)
return ch
def delete_charge(db: Session, tenant_id: int, sheet_id: int, charge_id: int) -> None:
from sqlalchemy import func
ch = (
db.query(RateCharge)
.filter(RateCharge.id == charge_id, RateCharge.rate_sheet_id == sheet_id,
RateCharge.tenant_id == tenant_id)
.first()
)
if not ch:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Cargo no encontrado")
ch.deleted_at = func.now()
db.commit()
# ============================================================ Importación Excel
# Plantillas por modo: encabezados esperados (orden libre, se detectan por nombre).
TEMPLATES: dict[str, list[str]] = {
"aereo": ["Region", "Origen", "Destino", "IATA", "Min", "100", "300", "500", "1000"],
"maritimo_fcl": ["Origen", "Destino", "Tipo contenedor", "Tarifa", "Transito", "Notas"],
"maritimo_lcl": ["Origen", "Destino", "Tarifa W/M", "Minimo", "Notas"],
"terrestre": ["Origen", "Destino", "Tarifa", "Transito", "Notas"],
}
def build_template(mode: str) -> bytes:
"""Genera un .xlsx con los encabezados del modo + una fila de ejemplo."""
import openpyxl
if mode not in TEMPLATES:
raise HTTPException(status_code=400, detail=f"Modo '{mode}' no válido")
wb = openpyxl.Workbook()
ws = wb.active
ws.title = mode
headers = TEMPLATES[mode]
ws.append(headers)
examples = {
"aereo": ["EUROPA", "NLU", "Frankfurt", "FRA", 190, 1.00, 1.00, 0.95, 0.90],
"maritimo_fcl": ["MXZLO", "CNSHA", "40HC", 2500, 28, "THC no incluido"],
"maritimo_lcl": ["MXZLO", "USLAX", 45, 80, "1 W/M = 1 ton o 1 m3"],
"terrestre": ["Monterrey", "Laredo", 850, 1, ""],
}
ws.append(examples[mode])
buf = io.BytesIO()
wb.save(buf)
return buf.getvalue()
def _num(v: Any) -> Decimal | None:
if v is None or v == "":
return None
try:
return Decimal(str(v).replace("$", "").replace(",", "").strip())
except Exception:
return None
def parse_excel(mode: str, content: bytes) -> ImportPreview:
"""Lee el Excel y devuelve una vista previa con validaciones (no persiste)."""
import openpyxl
if mode not in TEMPLATES:
raise HTTPException(status_code=400, detail=f"Modo '{mode}' no válido")
try:
wb = openpyxl.load_workbook(io.BytesIO(content), data_only=True, read_only=True)
except Exception:
raise HTTPException(status_code=400, detail="No se pudo leer el archivo Excel")
ws = wb.active
rows_iter = ws.iter_rows(values_only=True)
header = next(rows_iter, None)
if not header:
raise HTTPException(status_code=400, detail="El archivo está vacío")
cols = [str(c).strip() if c is not None else "" for c in header]
idx = {name.lower(): i for i, name in enumerate(cols)}
def cell(row, name):
i = idx.get(name.lower())
return row[i] if i is not None and i < len(row) else None
preview_rows: list[ImportPreviewRow] = []
valid = 0
for n, row in enumerate(rows_iter, start=2):
if row is None or all(c is None or str(c).strip() == "" for c in row):
continue
errors: list[str] = []
warnings: list[str] = []
data: dict = {}
if mode == "aereo":
data = {
"region": cell(row, "Region"),
"origin": cell(row, "Origen"),
"destination": cell(row, "Destino") or cell(row, "IATA"),
"iata": cell(row, "IATA"),
"min_charge": _num(cell(row, "Min")),
"breaks": {b: _num(cell(row, b)) for b in ("100", "300", "500", "1000")},
}
if not data["destination"]:
errors.append("Falta destino/IATA")
if not any(v is not None for v in data["breaks"].values()):
errors.append("Sin tarifas por quiebre")
elif mode == "maritimo_fcl":
data = {
"origin": cell(row, "Origen"),
"destination": cell(row, "Destino"),
"equipment_type": cell(row, "Tipo contenedor"),
"flat_rate": _num(cell(row, "Tarifa")),
"transit_days": _num(cell(row, "Transito")),
"notes": cell(row, "Notas"),
}
if data["flat_rate"] is None:
errors.append("Falta la tarifa")
if not data["equipment_type"]:
warnings.append("Sin tipo de contenedor")
elif mode == "maritimo_lcl":
data = {
"origin": cell(row, "Origen"),
"destination": cell(row, "Destino"),
"wm_rate": _num(cell(row, "Tarifa W/M")),
"min_charge": _num(cell(row, "Minimo")),
"notes": cell(row, "Notas"),
}
if data["wm_rate"] is None:
errors.append("Falta la tarifa W/M")
else: # terrestre
data = {
"origin": cell(row, "Origen"),
"destination": cell(row, "Destino"),
"flat_rate": _num(cell(row, "Tarifa")),
"transit_days": _num(cell(row, "Transito")),
"notes": cell(row, "Notas"),
}
if data["flat_rate"] is None:
errors.append("Falta la tarifa")
if not data.get("destination"):
errors.append("Falta destino")
ok = not errors
if ok:
valid += 1
preview_rows.append(ImportPreviewRow(row=n, data=_jsonable(data), ok=ok,
warnings=warnings, errors=errors))
return ImportPreview(mode=mode, total=len(preview_rows), valid=valid,
rows=preview_rows, columns=cols)
def _jsonable(d: dict) -> dict:
out = {}
for k, v in d.items():
if isinstance(v, Decimal):
out[k] = float(v)
elif isinstance(v, dict):
out[k] = {kk: (float(vv) if isinstance(vv, Decimal) else vv) for kk, vv in v.items()}
else:
out[k] = v
return out
def _rows_to_lanes(mode: str, rows: list[ImportPreviewRow], default_origin: str | None) -> list[RateLaneCreate]:
lanes: list[RateLaneCreate] = []
for r in rows:
if not r.ok:
continue
d = r.data
origin = d.get("origin") or default_origin
if mode == "aereo":
breaks = [
{"from_qty": Decimal(b), "rate": Decimal(str(v))}
for b, v in (d.get("breaks") or {}).items() if v is not None
]
lanes.append(RateLaneCreate(
origin=str(origin) if origin else None,
destination=str(d.get("destination")),
region=d.get("region"), rate_unit="per_kg",
min_charge=_num(d.get("min_charge")),
breaks=breaks, # type: ignore[arg-type]
))
elif mode == "maritimo_fcl":
lanes.append(RateLaneCreate(
origin=str(origin) if origin else None, destination=str(d.get("destination")),
equipment_type=d.get("equipment_type"), rate_unit="per_container",
flat_rate=_num(d.get("flat_rate")),
transit_days=int(d["transit_days"]) if d.get("transit_days") else None,
notes=d.get("notes"),
))
elif mode == "maritimo_lcl":
lanes.append(RateLaneCreate(
origin=str(origin) if origin else None, destination=str(d.get("destination")),
rate_unit="per_wm", min_charge=_num(d.get("min_charge")),
breaks=[{"from_qty": Decimal(0), "rate": Decimal(str(d["wm_rate"]))}], # type: ignore[arg-type]
notes=d.get("notes"),
))
else:
lanes.append(RateLaneCreate(
origin=str(origin) if origin else None, destination=str(d.get("destination")),
rate_unit="flat", flat_rate=_num(d.get("flat_rate")),
transit_days=int(d["transit_days"]) if d.get("transit_days") else None,
notes=d.get("notes"),
))
return lanes
def confirm_import(db: Session, tenant_id: int, company_id: int, data: ImportConfirm,
user_id: str | None) -> RateSheet:
"""Crea el tarifario + rutas a partir de la vista previa confirmada."""
sheet = RateSheet(
tenant_id=tenant_id, company_id=company_id,
supplier_id=data.supplier_id, mode=data.mode, name=data.name,
currency=data.currency, valid_from=data.valid_from, valid_to=data.valid_to,
default_origin=data.default_origin, status=data.status or "borrador",
notes=data.notes, created_by=user_id, updated_by=user_id,
)
db.add(sheet)
db.flush()
for lane in data.lanes:
_add_lane(db, tenant_id, company_id, sheet.id, lane)
db.commit()
db.refresh(sheet)
return sheet
def import_from_excel(db: Session, tenant_id: int, company_id: int, mode: str,
content: bytes, header: RateSheetCreate, user_id: str | None) -> RateSheet:
"""Atajo: parsea el Excel y crea el tarifario en un solo paso."""
preview = parse_excel(mode, content)
lanes = _rows_to_lanes(mode, preview.rows, header.default_origin)
return confirm_import(
db, tenant_id, company_id,
ImportConfirm(**header.model_dump(), lanes=lanes), user_id,
)
# ============================================================ Motor de costeo
def _volumetric_kg(volume_m3: Decimal | None) -> Decimal:
return (volume_m3 or Decimal(0)) * AIR_VOLUMETRIC_FACTOR
def _rate_for(breaks: list[RateBreak], qty: Decimal) -> Decimal | None:
"""Tarifa aplicable al peso/wm 'qty' (mayor quiebre cuyo umbral <= qty)."""
if not breaks:
return None
applicable = None
for b in breaks:
if b.from_qty <= qty:
applicable = b.rate
if applicable is None:
applicable = breaks[0].rate # por debajo del primer quiebre → tarifa base (gobierna el mínimo)
return applicable
def _best_break_cost(breaks: list[RateBreak], qty: Decimal) -> Decimal:
"""Costo base con optimización de quiebre (declarar peso mayor si conviene)."""
base_rate = _rate_for(breaks, qty)
base = (qty * base_rate) if base_rate is not None else Decimal(0)
for b in breaks:
if b.from_qty > qty:
candidate = b.from_qty * b.rate
if candidate < base:
base = candidate
return base
def _apply_charges(db: Session, sheet: RateSheet, lane: RateLane, base: Decimal,
chargeable: Decimal, quantity: int, dangerous: bool) -> list[CostChargeLine]:
charges = (
db.query(RateCharge)
.filter(
RateCharge.deleted_at.is_(None),
or_(RateCharge.rate_sheet_id == sheet.id, RateCharge.rate_lane_id == lane.id),
)
.all()
)
lines: list[CostChargeLine] = []
for c in charges:
if c.concept == "dgr" and not dangerous:
continue
v = c.value or Decimal(0)
if c.charge_type == "fijo" or c.charge_type == "por_guia":
amt = v
elif c.charge_type == "por_kg":
amt = v * chargeable
elif c.charge_type == "por_contenedor":
amt = v * quantity
elif c.charge_type == "porcentaje":
amt = base * v / Decimal(100)
else:
amt = v
lines.append(CostChargeLine(concept=c.concept, amount=amt))
return lines
def lane_locations(db: Session, tenant_id: int, company_id: int, mode: str) -> dict[str, list[str]]:
"""Orígenes/destinos existentes en los tarifarios activos de un modo.
Alinea el cotizador con las rutas realmente cotizables (los códigos provienen
de las lanes, por lo que el costeo siempre encontrará ruta).
"""
sheets = _sheet_query(db, tenant_id, company_id).filter(
RateSheet.mode == mode, RateSheet.status == "activo",
).all()
origins: set[str] = set()
destinations: set[str] = set()
for sheet in sheets:
lanes = db.query(RateLane).filter(
RateLane.rate_sheet_id == sheet.id, RateLane.deleted_at.is_(None),
).all()
for lane in lanes:
origin = lane.origin or sheet.default_origin
if origin:
origins.add(origin)
if lane.destination:
destinations.add(lane.destination)
return {"origins": sorted(origins), "destinations": sorted(destinations)}
def quote_cost(db: Session, tenant_id: int, company_id: int, req: CostRequest) -> list[CostOption]:
on_date = req.on_date or date.today()
sheets = _sheet_query(db, tenant_id, company_id).filter(
RateSheet.mode == req.mode,
RateSheet.status == "activo",
or_(RateSheet.valid_from.is_(None), RateSheet.valid_from <= on_date),
or_(RateSheet.valid_to.is_(None), RateSheet.valid_to >= on_date),
).all()
gross = req.gross_weight_kg or Decimal(0)
options: list[CostOption] = []
for sheet in sheets:
lanes_q = db.query(RateLane).filter(
RateLane.rate_sheet_id == sheet.id, RateLane.deleted_at.is_(None),
)
if req.destination:
lanes_q = lanes_q.filter(RateLane.destination == req.destination)
for lane in lanes_q.all():
# Origen: match exacto o el default del tarifario.
lane_origin = lane.origin or sheet.default_origin
if req.origin and lane_origin and lane_origin != req.origin:
continue
if req.mode == "maritimo_fcl":
if req.equipment_type and lane.equipment_type and lane.equipment_type != req.equipment_type:
continue
chargeable = Decimal(req.quantity)
base = (lane.flat_rate or Decimal(0)) * req.quantity
detail = f"{req.quantity} x {lane.equipment_type or 'contenedor'}"
elif req.mode == "terrestre":
chargeable = Decimal(req.quantity)
base = (lane.flat_rate or Decimal(0)) * req.quantity
detail = "tarifa por ruta"
elif req.mode == "maritimo_lcl":
tons = gross / Decimal(1000)
wm = max(tons, req.volume_m3 or Decimal(0))
brks = breaks_of(db, lane.id)
base = _best_break_cost(brks, wm) if brks else Decimal(0)
chargeable = wm
base = max(base, lane.min_charge or Decimal(0))
detail = f"W/M {wm.quantize(Decimal('0.01'))}"
else: # aereo
# P/Vol por dimensiones (L×A×H×cant / 6000); si no hay dimensiones,
# respaldo con el volumen en m³ × 167.
vol_by_dims = air_volumetric_kg(req.length_cm, req.width_cm, req.height_cm, req.quantity)
volumetric = vol_by_dims if vol_by_dims > 0 else _volumetric_kg(req.volume_m3)
chargeable = max(gross, volumetric)
brks = breaks_of(db, lane.id)
base = _best_break_cost(brks, chargeable)
base = max(base, lane.min_charge or Decimal(0))
detail = f"facturable {chargeable.quantize(Decimal('0.01'))} kg (P/Vol)"
charge_lines = _apply_charges(db, sheet, lane, base, chargeable, req.quantity, req.dangerous)
total = base + sum((c.amount for c in charge_lines), Decimal(0))
options.append(CostOption(
rate_sheet_id=sheet.id, rate_sheet_name=sheet.name, supplier_id=sheet.supplier_id,
currency=sheet.currency, chargeable=chargeable, base_cost=base,
charges=charge_lines, total_cost=total, transit_days=lane.transit_days, detail=detail,
))
options.sort(key=lambda o: o.total_cost)
return options

11
backend/api/v1/modules/crm/router.py
View File

@@ -13,14 +13,18 @@ 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
from .expediente_gateway.routes import router as expediente_gateway_router
from .leads.routes import router as leads_router
from .metrics.routes import router as metrics_router
from .opportunities.routes import router as opportunities_router
from .pipelines.routes import router as pipelines_router
from .quotes.routes import router as quotes_router
from .rates.routes import cost_router as rates_cost_router
from .rates.routes import router as rates_router
from .service_requests.routes import router as service_requests_router
from .suppliers.routes import router as suppliers_router
from .uploads.routes import router as uploads_router
@@ -41,6 +45,13 @@ 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)
router.include_router(rates_router)
router.include_router(rates_cost_router)
# Tablero de operación del carril hacia EFC: cola pendiente, métricas y reintento manual.
# No es una ruta de negocio; existe para que una persona vea y desatore la entrega sin
# entrar a la base. Hereda el enforcement de crm.access del router agregador.
router.include_router(expediente_gateway_router)

95
backend/api/v1/modules/crm/service_requests/dto.py
View File

@@ -7,22 +7,66 @@ from pydantic import BaseModel, ConfigDict, Field
class ServiceRequestBase(BaseModel):
reference: str | None = Field(None, max_length=40)
account_id: int | None = None
contact_id: int | None = None
opportunity_id: int | None = None
operation_type: str = Field(..., max_length=20) # importacion | exportacion
transport_mode: str | None = Field(None, max_length=20)
service_type: str | None = Field(None, max_length=20)
incoterm: str | None = Field(None, max_length=10)
# Ruta legada (texto libre) — se conserva por compatibilidad
origin: str | None = Field(None, max_length=160)
destination: str | None = Field(None, max_length=160)
# Ruta estructurada (país por catálogo ISO; ciudad/puerto por catálogo o texto)
origin_country: str | None = Field(None, max_length=3)
origin_city: str | None = Field(None, max_length=120)
origin_port: str | None = Field(None, max_length=20)
destination_country: str | None = Field(None, max_length=3)
destination_city: str | None = Field(None, max_length=120)
destination_port: str | None = Field(None, max_length=20)
pickup_location: str | None = Field(None, max_length=255)
delivery_location: str | None = Field(None, max_length=255)
cargo_type: str | None = Field(None, max_length=120)
weight: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=3)
weight: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=3) # peso bruto
volume: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=3)
load_type: str | None = Field(None, max_length=10)
load_type: str | None = Field(None, max_length=10) # FCL | LCL | AMBAS
container_equipment: str | None = Field(None, max_length=120)
container_count: int | None = Field(None, ge=0)
commodity: str | None = None
required_date: date | None = None
request_date: date | None = None
estimated_shipment_date: date | None = None
currency: str | None = Field(None, max_length=3)
priority: str | None = Field(None, max_length=20)
# Mercancía
cargo_value: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=2)
insurance_required: bool = False
hs_code: str | None = Field(None, max_length=20)
goods_origin_country: str | None = Field(None, max_length=3)
hazardous_imo: bool = False
refrigerated: bool = False
stackable: bool = False
# Dimensiones y bultos
pieces_count: int | None = Field(None, ge=0)
boxes_count: int | None = Field(None, ge=0)
pallets_count: int | None = Field(None, ge=0)
net_weight: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=3)
length_cm: Decimal | None = Field(None, ge=0, max_digits=10, decimal_places=2)
width_cm: Decimal | None = Field(None, ge=0, max_digits=10, decimal_places=2)
height_cm: Decimal | None = Field(None, ge=0, max_digits=10, decimal_places=2)
measurement_unit: str | None = Field(None, max_length=20)
# LCL
packaging_type: str | None = Field(None, max_length=20)
oversized: bool = False
weight_per_pallet: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=3)
volume_per_pallet: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=3)
# Servicios adicionales (códigos del catálogo servicio_adicional) y pago
additional_services: list[str] | None = None
additional_service_costs: dict[str, float] | None = None # {codigo: costo estimado}
payment_method: str | None = Field(None, max_length=20)
destination_agent_id: int | None = None
requirements: str | None = None
client_notes: str | None = None
internal_notes: str | None = None
status: str = Field("nueva", max_length=20)
notes: str | None = None
owner_user_id: str | None = Field(None, max_length=64)
@@ -38,8 +82,12 @@ class ServiceRequestContactInput(BaseModel):
class ServiceRequestFromOpportunityInput(BaseModel):
"""Datos para convertir una oportunidad del embudo en solicitud/RFQ (R-C-02)."""
operation_type: str = Field(..., max_length=20) # importacion | exportacion
"""Datos para convertir una oportunidad del embudo en solicitud/RFQ (R-C-02).
La dirección impo/expo se hereda de la oportunidad; ``operation_type`` aquí es
solo un respaldo para oportunidades antiguas que no la tengan capturada.
"""
operation_type: str | None = Field(None, max_length=20) # importacion | exportacion
transport_mode: str | None = Field(None, max_length=20)
service_type: str | None = Field(None, max_length=20)
incoterm: str | None = Field(None, max_length=10)
@@ -51,6 +99,7 @@ class ServiceRequestFromOpportunityInput(BaseModel):
class ServiceRequestUpdate(BaseModel):
reference: str | None = Field(None, max_length=40)
account_id: int | None = None
contact_id: int | None = None
opportunity_id: int | None = None
operation_type: str | None = Field(None, max_length=20)
transport_mode: str | None = Field(None, max_length=20)
@@ -58,15 +107,52 @@ class ServiceRequestUpdate(BaseModel):
incoterm: str | None = Field(None, max_length=10)
origin: str | None = Field(None, max_length=160)
destination: str | None = Field(None, max_length=160)
origin_country: str | None = Field(None, max_length=3)
origin_city: str | None = Field(None, max_length=120)
origin_port: str | None = Field(None, max_length=20)
destination_country: str | None = Field(None, max_length=3)
destination_city: str | None = Field(None, max_length=120)
destination_port: str | None = Field(None, max_length=20)
pickup_location: str | None = Field(None, max_length=255)
delivery_location: str | None = Field(None, max_length=255)
cargo_type: str | None = Field(None, max_length=120)
weight: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=3)
volume: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=3)
load_type: str | None = Field(None, max_length=10)
container_equipment: str | None = Field(None, max_length=120)
container_count: int | None = Field(None, ge=0)
commodity: str | None = None
required_date: date | None = None
request_date: date | None = None
estimated_shipment_date: date | None = None
currency: str | None = Field(None, max_length=3)
priority: str | None = Field(None, max_length=20)
cargo_value: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=2)
insurance_required: bool | None = None
hs_code: str | None = Field(None, max_length=20)
goods_origin_country: str | None = Field(None, max_length=3)
hazardous_imo: bool | None = None
refrigerated: bool | None = None
stackable: bool | None = None
pieces_count: int | None = Field(None, ge=0)
boxes_count: int | None = Field(None, ge=0)
pallets_count: int | None = Field(None, ge=0)
net_weight: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=3)
length_cm: Decimal | None = Field(None, ge=0, max_digits=10, decimal_places=2)
width_cm: Decimal | None = Field(None, ge=0, max_digits=10, decimal_places=2)
height_cm: Decimal | None = Field(None, ge=0, max_digits=10, decimal_places=2)
measurement_unit: str | None = Field(None, max_length=20)
packaging_type: str | None = Field(None, max_length=20)
oversized: bool | None = None
weight_per_pallet: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=3)
volume_per_pallet: Decimal | None = Field(None, ge=0, max_digits=14, decimal_places=3)
additional_services: list[str] | None = None
additional_service_costs: dict[str, float] | None = None
payment_method: str | None = Field(None, max_length=20)
destination_agent_id: int | None = None
requirements: str | None = None
client_notes: str | None = None
internal_notes: str | None = None
status: str | None = Field(None, max_length=20)
notes: str | None = None
owner_user_id: str | None = Field(None, max_length=64)
@@ -76,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

54
backend/api/v1/modules/crm/service_requests/models.py
View File

@@ -1,6 +1,6 @@
from datetime import date, datetime
from sqlalchemy import Date, DateTime, ForeignKey, Integer, Numeric, String, Text, text
from sqlalchemy import JSON, Boolean, Date, DateTime, ForeignKey, Integer, Numeric, String, Text, text
from sqlalchemy.orm import Mapped, mapped_column
from api.v1.common.base_models import TenantScopedMixin, TimestampMixin
@@ -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
)
@@ -57,6 +58,57 @@ class ServiceRequest(Base, TenantScopedMixin, TimestampMixin):
created_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
updated_by: Mapped[str | None] = mapped_column(String(64), nullable=True)
# ----- Campos del documento maestro de cotización (T2026-08) -----
# Datos generales
contact_id: Mapped[int | None] = mapped_column(
Integer, ForeignKey("crm.contacts.id"), nullable=True, index=True
)
request_date: Mapped[date | None] = mapped_column(Date, nullable=True) # fecha de la solicitud
currency: Mapped[str | None] = mapped_column(String(3), nullable=True)
priority: Mapped[str | None] = mapped_column(String(20), nullable=True) # baja|normal|alta|urgente
# Ruta (país por catálogo ISO; ciudad/puerto por catálogo o texto libre)
origin_country: Mapped[str | None] = mapped_column(String(3), nullable=True)
origin_city: Mapped[str | None] = mapped_column(String(120), nullable=True)
origin_port: Mapped[str | None] = mapped_column(String(20), nullable=True)
destination_country: Mapped[str | None] = mapped_column(String(3), nullable=True)
destination_city: Mapped[str | None] = mapped_column(String(120), nullable=True)
destination_port: Mapped[str | None] = mapped_column(String(20), nullable=True)
pickup_location: Mapped[str | None] = mapped_column(String(255), nullable=True)
delivery_location: Mapped[str | None] = mapped_column(String(255), nullable=True)
estimated_shipment_date: Mapped[date | None] = mapped_column(Date, nullable=True)
# Mercancía
cargo_value: Mapped[float | None] = mapped_column(Numeric(14, 2), nullable=True)
insurance_required: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
hs_code: Mapped[str | None] = mapped_column(String(20), nullable=True) # fracción arancelaria
goods_origin_country: Mapped[str | None] = mapped_column(String(3), nullable=True) # país de origen de la mercancía
hazardous_imo: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
refrigerated: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
stackable: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
# Dimensiones y bultos
pieces_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
boxes_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
pallets_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
net_weight: Mapped[float | None] = mapped_column(Numeric(14, 3), nullable=True) # peso neto (weight = bruto)
length_cm: Mapped[float | None] = mapped_column(Numeric(10, 2), nullable=True)
width_cm: Mapped[float | None] = mapped_column(Numeric(10, 2), nullable=True)
height_cm: Mapped[float | None] = mapped_column(Numeric(10, 2), nullable=True)
measurement_unit: Mapped[str | None] = mapped_column(String(20), nullable=True)
# FCL
container_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
# LCL
packaging_type: Mapped[str | None] = mapped_column(String(20), nullable=True)
oversized: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default=text("false"))
weight_per_pallet: Mapped[float | None] = mapped_column(Numeric(14, 3), nullable=True)
volume_per_pallet: Mapped[float | None] = mapped_column(Numeric(14, 3), nullable=True)
# Servicios adicionales (lista de códigos del catálogo servicio_adicional) y pago
additional_services: Mapped[list | None] = mapped_column(JSON, nullable=True)
# Costo estimado por servicio adicional marcado: {codigo: costo}
additional_service_costs: Mapped[dict | None] = mapped_column(JSON, nullable=True)
payment_method: Mapped[str | None] = mapped_column(String(20), nullable=True)
# Notas
client_notes: Mapped[str | None] = mapped_column(Text, nullable=True)
internal_notes: Mapped[str | None] = mapped_column(Text, nullable=True)
class RateRequest(Base, TenantScopedMixin, TimestampMixin):
"""Solicitud de tarifa a un proveedor para una solicitud de servicio (Diagrama 1, paso 6)."""

42
backend/api/v1/modules/crm/service_requests/service.py
View File

@@ -4,7 +4,10 @@ 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
from ..opportunities.models import Opportunity
from ..suppliers.models import Supplier
from .dto import (
@@ -37,6 +40,8 @@ def _exists(db: Session, model, _id: int | None, tenant_id: int, company_id: int
def _validate_request_refs(db: Session, data: dict, tenant_id: int, company_id: int) -> None:
if not _exists(db, Account, data.get("account_id"), tenant_id, company_id):
raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="El cliente asociado no existe")
if not _exists(db, Contact, data.get("contact_id"), tenant_id, company_id):
raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="El contacto asociado no existe")
if not _exists(db, Supplier, data.get("destination_agent_id"), tenant_id, company_id):
raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="El agente en destino no existe")
if not _exists(db, Opportunity, data.get("opportunity_id"), tenant_id, company_id):
@@ -103,6 +108,15 @@ def create_service_request(
data = payload.model_dump()
_validate_request_refs(db, data, tenant_id, company_id)
obj = ServiceRequest(**data, tenant_id=tenant_id, company_id=company_id, created_by=user_id, updated_by=user_id)
# 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)
@@ -166,10 +180,24 @@ def create_from_opportunity(
)
if not opp:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Oportunidad no encontrada")
# Idempotente: si la oportunidad ya se convirtió, devuelve la misma solicitud
if opp.converted_service_request_id:
existing = get_service_request(db, opp.converted_service_request_id, tenant_id, company_id)
return existing
# La dirección impo/expo se hereda de la oportunidad (respaldo: el payload)
operation_type = opp.operation_type or payload.operation_type
if not operation_type:
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
detail="Define la dirección (importación/exportación) en la oportunidad para convertirla",
)
obj = ServiceRequest(
account_id=opp.account_id,
contact_id=opp.contact_id,
opportunity_id=opp.id,
operation_type=payload.operation_type,
operation_type=operation_type,
transport_mode=payload.transport_mode,
service_type=payload.service_type,
incoterm=payload.incoterm,
@@ -178,12 +206,24 @@ def create_from_opportunity(
status="nueva",
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,
updated_by=user_id,
)
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()
db.refresh(obj)
return obj

2
backend/api/v1/modules/crm/suppliers/dto.py
View File

@@ -13,6 +13,7 @@ class SupplierBase(BaseModel):
person_type: str | None = Field(None, max_length=10)
status: str = Field("active", max_length=20)
classifications: list[str] = Field(default_factory=list)
classification_other: str | None = Field(None, max_length=120)
# Comercial
services_offered: str | None = None
coverage: str | None = Field(None, max_length=20)
@@ -52,6 +53,7 @@ class SupplierUpdate(BaseModel):
person_type: str | None = Field(None, max_length=10)
status: str | None = Field(None, max_length=20)
classifications: list[str] | None = None
classification_other: str | None = Field(None, max_length=120)
services_offered: str | None = None
coverage: str | None = Field(None, max_length=20)
countries: list[str] | None = None

2
backend/api/v1/modules/crm/suppliers/models.py
View File

@@ -30,6 +30,8 @@ class Supplier(Base, TenantScopedMixin, TimestampMixin):
# Clasificación (múltiple): naviera, aerolinea, transportista_terrestre, ferrocarril,
# agente_aduanal, agente_carga, agente_corresponsal, almacen, aseguradora, paqueteria, otro
classifications: Mapped[list | None] = mapped_column(JSON, nullable=True, default=list)
# Texto libre cuando la clasificación incluye "otro"
classification_other: Mapped[str | None] = mapped_column(String(120), nullable=True)
# ----- Información comercial -----
services_offered: Mapped[str | None] = mapped_column(Text, nullable=True)

30
backend/api/v1/modules/crm/uploads/routes.py
View File

@@ -7,10 +7,10 @@ pide una URL firmada fresca en ``/uploads/url`` (las presignadas expiran).
import re
import uuid
from fastapi import APIRouter, Depends, File, HTTPException, Query, UploadFile, status
from fastapi import APIRouter, Depends, File, HTTPException, Query, Response, UploadFile, status
from core.security import get_current_user
from core.storage_s3 import presigned_get_url, put_object_bytes
from core.storage_s3 import get_object_bytes, presigned_get_url, put_object_bytes
router = APIRouter()
@@ -61,3 +61,29 @@ def get_upload_url(
if not key.startswith(prefix):
raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Archivo fuera de tu alcance")
return {"url": presigned_get_url(key)}
@router.get("/uploads/download")
def download_file(
key: str = Query(..., description="Object key del archivo en el almacén"),
company_id: int = Query(..., description="Company ID"),
current_user: dict = Depends(get_current_user),
):
"""Transmite el archivo por el backend (sin exponer MinIO al navegador).
Evita el bug de la URL prefirmada que apunta al host interno ``minio:9000``.
"""
tenant_id = current_user["tenant_id"]
prefix = f"tenants/{tenant_id}/companies/{company_id}/"
if not key.startswith(prefix):
raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Archivo fuera de tu alcance")
try:
data = get_object_bytes(key)
except Exception:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Archivo no encontrado")
filename = key.rsplit("/", 1)[-1]
return Response(
content=data,
media_type="application/octet-stream",
headers={"Content-Disposition": f'inline; filename="{filename}"'},
)