Finanzas en Sevastopol

Propósito

El dominio finanzas del frontend cubre el ciclo completo de la cuenta bancaria del tenant — desde la cartola (lo que el banco reportó) hasta el libro contable (lo que la empresa registró) — y los mecanismos para resolver las diferencias entre ambos. Cinco islands montadas sobre el mismo proxy /api/financieros se reparten el trabajo.

Ubicación

• Directorysevastopol/src/components/islands/financieros/

  • BancosIsland.tsx
  • CartolasIsland.tsx
  • ConciliacionBancariaIsland.tsx
  • LibroBancoIsland.tsx
  • PrestamosIsland.tsx
  • FinancierosWorkspace.tsx — tokens visuales compartidos por las 5 islands
• Directorysevastopol/src/pages/api/financieros/

  • […all].ts — proxy genérico vía createProxy(“/api/financieros”)

Flujo del dominio

flowchart LR
  subgraph FUENTE["Fuente bancaria"]
    XLSX[("XLSX del banco")]
    ETL["ETL"]
    CART["Cartolas Island"]
  end

  subgraph CONTABLE["Lado contable"]
    SISTEMA["Documentos sistema<br/>compras · ventas · F29"]
    LB["Libro Banco Island"]
  end

  subgraph MATCH["Conciliación"]
    CONC["Conciliación Bancaria Island"]
    DIF["Diferencias"]
    RES["Resoluciones<br/>castigo · compensación"]
  end

  subgraph MAESTRO["Catálogo"]
    BAN["Bancos Island"]
    CAT["Categorías movimiento"]
    PRE["Préstamos Island"]
  end

  XLSX --> ETL --> CART
  CART --> CONC
  SISTEMA --> CONC
  CONC -- pendientes --> CONC
  CONC -- vincular/manual --> LB
  LB --> DIF --> RES
  PRE -- pago de cuota --> CONC
  BAN -. catálogo .-> CART
  BAN -. catálogo .-> CONC
  BAN -. catálogo .-> LB
  BAN -. catálogo .-> PRE
  CAT -. categoría .-> CONC
  CAT -. categoría .-> LB

Lenguaje compartido

Las 5 islands comparten varios elementos del FinancierosWorkspace:

Componente	Uso
FinancierosWorkspaceHeader	Header con pills, controls y note.
InlineMetricPill	Métricas inline (vista, contadores, totales). Tonos success, warning, default.
WorkspaceSectionCard	Sección con eyebrow, title, description, pills y maxHeight opcional.
WorkspaceTabBar	Tabs principales por island.
WorkspaceSegmentedControl	Filtros estilo “Todos / Pendientes / Cerrados”.
WORKSPACE_SCROLL_HEIGHT	Constante de altura para tablas largas.
Botones tonalizados	workspacePrimaryButtonClass, workspaceSecondaryButtonClass, workspaceWarningButtonClass, workspaceDangerButtonClass, workspaceSuccessButtonClass.
Inputs tonalizados	workspaceFieldClass, workspaceCompactFieldClass, workspaceFieldLabelClass.

Hooks compartidos

Hook	Consumen	Comportamiento por island
useActiveTenant	Las 5	Limpia estado local y recarga catálogos al cambiar tenant.
useActivePeriod	Bancos, Cartolas, Conciliación, Libro Banco	Bancos mueve fechaHasta al último día del mes; las otras tres lo usan al pulsar Cargar período. Préstamos no lo consume.

useActivePeriod no dispara re-fetch automático en este dominio (excepto Bancos que recalcula el saldo) — el operador suele cambiar varios filtros y un fetch reactivo interrumpiría la edición.

API base y proxy

Todas las islands llaman a /api/financieros/*. El proxy reenvía a Orchestrator vía createProxy("/api/financieros") (ver BFF Proxy).

Excepciones — endpoints fuera del dominio que algunas islands consumen:

Island	Endpoint externo	Para
Bancos	/api/admin/chart-of-accounts	Plan de cuentas imputables para selectores.
Libro Banco	/api/admin/chart-of-accounts	Igual.
Conciliación Bancaria	/api/financieros/categorias-movimiento	Categorías compartidas con Libro Banco.

Navegación cross-island

Origen	Destino	Mecanismo
CicloContableIsland paso incobrables	Libro Banco	window.dispatchEvent(new CustomEvent("sidebar:navigate", { detail: "LibroBancoView" }))
Libro Banco diferencia → Compensaciones	(pestaña interna)	switchTab("compensaciones") + loadCompensacionProveedorDocumento(id)
Conciliación vincular → Libro	(read implícito)	El operador refresca LibroBancoIsland para ver el movimiento ya con categoría/cuenta.

Backend de referencia

Service	Cubre
FinancierosService	Bancos, categorías, cuentas bancarias.
MovimientosService	Cartola, movimientos manuales, ETL.
ConciliacionService	Vinculación, conciliación manual, castigo, compensación, resoluciones.
AnticiposProveedorService	Anticipos como pseudo-movimiento bancario.
PrestamosService	Préstamos y amortización.

Decisiones de UX compartidas

Decisión	Aplica a	Motivo
Filtros locales sobre Promise.all de fetch grande	Todas excepto Préstamos	Volúmenes manejables por tenant/mes; paginar agregaría latencia perceptible.
Cargas en paralelo al cambiar tenant	Bancos, Conciliación, Libro Banco	Tres catálogos independientes; serializar es visible.
Tabla con Cargo y Abono en columnas separadas	Cartolas, Libro Banco	Lectura tipo libro mayor; no inferir signo del monto.
:::caution::: antes de operaciones destructivas	Eliminar movimiento, regenerar amortización, desconciliar, castigar, compensar, reversar resolución	Cada una afecta lado contable o tabla maestra.
Saldo bancario al cierre del mes activo, no a hoy	Bancos	El operador piensa en términos contables, no en tiempo real.
Botón Cargar período explícito	Conciliación, Libro Banco	Los 3 fetch en paralelo son pesados; lanzarlos en cada cambio de filtro castigaría al backend.