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

feat(ops,fin,crm): reglas de negocio del PDF (decisiones, cierre, facturación, continuidad, RBAC)

Browse Source 
Cierra los huecos de la auditoría contra "SOFTWARE PARA AGENTES DE CARGA":

- ops (Diag. 2/3): bitácora con puntos de decisión (kind=decision) y ciclo de
  corrección (parent_event_id/attempt) para ¿Cut Off? y ¿despacho autorizado?
  (R-E-05/13, R-I-06). Reprogramación de salida (previous_etd, R-E-06). Hitos
  operativos completos export/import. Cierre operativo con costos finales
  (close_shipment, R-E-22).
- fin (Diag. 4): facturación con gate por cierre operativo y sin duplicar
  (R-F-01), costos de operación arrastrados (ops_cost_total, R-F-02), envío con
  PDF generado y guardado en MinIO (send_invoice + pdf.py sin dependencias,
  R-F-05) y revisión del cliente (en_revision_cliente + aprobación, R-F-06).
- crm (Diag. 1): opportunity_id enlaza embudo→RFQ (R-C-02), contacto como etapa
  (first_contact_at, R-C-04), re-cotización (clone_quote + reopen, R-C-12).
- transversal: catálogo de Incoterms y participantes/actores incl. autoridad
  aduanera (R-T-01/10), enforcement de permisos por carril (RBAC) con roles
  sembrados y dependencias dev-safe (R-T-07).
- Migración d5e6f7a8b9c0 con downgrade. Seed extendido. 70 tests (12 nuevos).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Aduanasoft
2026-07-15 08:46:53 -06:00
parent 116d2e7f5a
commit e79705e6e3
26 changed files with 1407 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

141
backend/api/v1/modules/fin/invoices/service.py
View File

@@ -9,8 +9,16 @@ from api.v1.modules.crm.accounts.models import Account
from api.v1.modules.crm.quotes.models import Quote, QuoteItem
from api.v1.modules.ops.shipments.models import Shipment
from .dto import InvoiceCreate, InvoiceItemCreate, InvoiceItemUpdate, InvoiceUpdate, PaymentCreate
from .dto import (
InvoiceClientReviewInput,
InvoiceCreate,
InvoiceItemCreate,
InvoiceItemUpdate,
InvoiceUpdate,
PaymentCreate,
)
from .models import Invoice, InvoiceItem, Payment
from .pdf import build_invoice_pdf
def _exists(db: Session, model, _id, tenant_id, company_id) -> bool:
@@ -52,7 +60,7 @@ def _recompute(db: Session, invoice: Invoice) -> None:
invoice.paid_amount = paid
invoice.balance = total - paid
# Estado de cobranza (no toca borrador ni cancelada)
if invoice.status in ("emitida", "enviada", "pagada"):
if invoice.status in ("emitida", "enviada", "en_revision_cliente", "pagada"):
if total > 0 and invoice.balance <= 0:
invoice.status = "pagada"
invoice.paid_at = datetime.now(timezone.utc)
@@ -131,8 +139,108 @@ def emit_invoice(db, invoice_id, tenant_id, company_id) -> Invoice:
return _set_status(db, invoice_id, tenant_id, company_id, "emitida", set_issue=True)
def send_invoice(db, invoice_id, tenant_id, company_id) -> Invoice:
return _set_status(db, invoice_id, tenant_id, company_id, "enviada", set_issue=True)
def _build_pdf_bytes(db, invoice: Invoice, tenant_id, company_id) -> bytes:
"""Arma los bytes del PDF de la factura a partir de sus datos y conceptos."""
items = get_items(db, invoice.id, tenant_id, company_id)
account_name = None
if invoice.account_id:
acc = db.query(Account).filter(Account.id == invoice.account_id).first()
account_name = acc.name if acc else None
return build_invoice_pdf(
folio=invoice.reference or f"FAC-{invoice.id}",
issue_date=str(invoice.issue_date or ""),
due_date=str(invoice.due_date or ""),
account_name=account_name or "Cliente",
currency=invoice.currency or "MXN",
items=[
{"concept": it.concept, "description": it.description, "quantity": it.quantity, "unit_amount": it.unit_amount}
for it in items
],
subtotal=invoice.subtotal,
tax_rate=invoice.tax_rate,
tax_amount=invoice.tax_amount,
total=invoice.total,
paid=invoice.paid_amount,
balance=invoice.balance,
bank_info=invoice.bank_info,
notes=invoice.notes,
)
def send_invoice(db, invoice_id, tenant_id, company_id, user_id=None) -> Invoice:
"""Envía la factura al cliente: genera el PDF, lo guarda en MinIO y marca 'enviada' (R-F-05)."""
from core.storage_s3 import put_object_bytes # import diferido: evita conectar en tests
obj = get_invoice(db, invoice_id, tenant_id, company_id)
if obj.status in ("borrador", "cancelada"):
# La factura debe estar emitida antes de enviarse al cliente
if obj.status == "cancelada":
raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="La factura está cancelada")
obj.status = "emitida"
if not obj.issue_date:
obj.issue_date = date.today()
db.flush()
pdf_bytes = _build_pdf_bytes(db, obj, tenant_id, company_id)
key = f"tenants/{tenant_id}/companies/{company_id}/fin-invoices/{obj.id}/factura-{obj.reference or obj.id}.pdf"
put_object_bytes(key, pdf_bytes, content_type="application/pdf")
obj.pdf_file_key = key
obj.status = "enviada"
obj.sent_at = datetime.now(timezone.utc)
if not obj.issue_date:
obj.issue_date = date.today()
obj.updated_by = user_id
db.commit()
db.refresh(obj)
return obj
def get_invoice_pdf_url(db, invoice_id, tenant_id, company_id) -> str:
"""Devuelve una URL firmada fresca del PDF de la factura (las presignadas expiran)."""
from core.storage_s3 import presigned_get_url
obj = get_invoice(db, invoice_id, tenant_id, company_id)
if not obj.pdf_file_key:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="La factura aún no tiene PDF; envíala al cliente para generarlo",
)
return presigned_get_url(obj.pdf_file_key)
def mark_client_review(db, invoice_id, tenant_id, company_id, user_id=None) -> Invoice:
"""Pone la factura en revisión del cliente (R-F-06)."""
obj = get_invoice(db, invoice_id, tenant_id, company_id)
if obj.status not in ("enviada", "en_revision_cliente"):
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="Solo una factura enviada puede pasar a revisión del cliente",
)
obj.status = "en_revision_cliente"
obj.updated_by = user_id
db.commit()
db.refresh(obj)
return obj
def client_review_decision(
db, invoice_id, payload: InvoiceClientReviewInput, tenant_id, company_id, user_id=None
) -> Invoice:
"""Registra la decisión de revisión del cliente: aprobada o con observaciones (R-F-06)."""
obj = get_invoice(db, invoice_id, tenant_id, company_id)
if obj.status not in ("enviada", "en_revision_cliente"):
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="La factura debe estar enviada o en revisión para registrar la decisión del cliente",
)
obj.client_reviewed_at = datetime.now(timezone.utc)
obj.client_approved = payload.approved
obj.review_notes = payload.notes
# Aprobada → lista para cobranza (enviada). Con observaciones → regresa a emitida para corregir.
obj.status = "enviada" if payload.approved else "emitida"
obj.updated_by = user_id
db.commit()
db.refresh(obj)
return obj
def cancel_invoice(db, invoice_id, tenant_id, company_id) -> Invoice:
@@ -140,12 +248,32 @@ def cancel_invoice(db, invoice_id, tenant_id, company_id) -> Invoice:
def generate_from_shipment(db, shipment_id, tenant_id, company_id, user_id=None) -> Invoice:
"""Genera la factura de un embarque, tomando los conceptos (venta) de su cotización."""
"""Genera la factura de un embarque, tomando los conceptos (venta) de su cotización.
El disparador válido de la facturación es el cierre operativo del embarque
(R-F-01): solo se factura un embarque en estado 'cerrada'. Los costos reales de
la operación se arrastran a la factura (R-F-02).
"""
shipment = db.query(Shipment).filter(
Shipment.id == shipment_id, Shipment.tenant_id == tenant_id, Shipment.company_id == company_id, Shipment.deleted_at.is_(None)
).first()
if not shipment:
raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Embarque no encontrado")
if shipment.status != "cerrada":
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="El embarque debe estar cerrado (cierre operativo) para facturarse",
)
existing = db.query(Invoice).filter(
Invoice.shipment_id == shipment_id, Invoice.tenant_id == tenant_id,
Invoice.company_id == company_id, Invoice.deleted_at.is_(None),
Invoice.status != "cancelada",
).first()
if existing:
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="El embarque ya tiene una factura vigente",
)
quote = None
if shipment.quote_id:
@@ -156,7 +284,8 @@ def generate_from_shipment(db, shipment_id, tenant_id, company_id, user_id=None)
shipment_id=shipment.id,
quote_id=shipment.quote_id,
account_id=shipment.account_id,
currency=quote.currency if quote else "MXN",
currency=(shipment.cost_currency or (quote.currency if quote else "MXN")),
ops_cost_total=shipment.actual_cost_total,
status="borrador",
tenant_id=tenant_id,
company_id=company_id,