mini-erp/mini-frontend/docs/flujo-documentos-marketing.md

# Flujo de Procesamiento — Documentos de Marketing (Ventas / Compras)

Cubre los documentos comerciales de SAP Business One que la app gestiona: Órdenes de Venta, Facturas de Venta, Órdenes de Compra y Facturas de Proveedor. Los cuatro comparten un único formulario genérico (`MarketingDocumentForm.tsx`) parametrizado por vista.

## Arquitectura General

```mermaid
graph TB
  subgraph "Frontend React (sap-frontend)"
    OL[OrdersList.tsx]
    O[Orders.tsx]
    IL[InvoicesList.tsx]
    I[Invoices.tsx]
    POL[PurchaseOrdersList.tsx]
    PO[PurchaseOrders.tsx]
    PIL[PurchaseInvoicesList.tsx]
    PI[PurchaseInvoices.tsx]
    FORM[MarketingDocumentForm.tsx]
    COPY[CopyFromModal.tsx]
    SEARCH[ModalSearchTemplate.tsx]
    BADGE[StatusBadge.tsx]
    LVT[ListViewTemplate.tsx]
    TYPES[types/sapMarketing.ts]
    API[api.ts]
  end

  subgraph "Backend FastAPI (mini-backend)"
    SALES[routers/sales.py]
    PURCH[routers/purchases.py]
    CORE[core/sap.py]
  end

  subgraph "SAP Business One"
    SL[Service Layer<br/>Orders / Invoices / PurchaseOrders / PurchaseInvoices]
  end

  OL --> LVT
  IL --> LVT
  POL --> LVT
  PIL --> LVT
  LVT --> BADGE

  O --> FORM
  I --> FORM
  PO --> FORM
  PI --> FORM
  FORM --> COPY
  FORM --> SEARCH
  FORM --> TYPES
  FORM --> API

  API -->|GET/POST/PATCH| SALES
  API -->|GET/POST/PATCH| PURCH
  SALES --> CORE
  PURCH --> CORE
  CORE --> SL
```

Cada vista de mantenimiento (`Orders.tsx`, `Invoices.tsx`, `PurchaseOrders.tsx`, `PurchaseInvoices.tsx`) es una capa delgada: mantiene el estado del documento (`doc`, tipado como `MarketingDocument` en `types/sapMarketing.ts`) y le pasa a `MarketingDocumentForm` la configuración específica de ese tipo de documento — el componente de formulario en sí no sabe si está editando una orden o una factura, solo renderiza lo que recibe por props.

## Cómo un solo formulario sirve a los 4 documentos

`MarketingDocumentForm` recibe por props todo lo que varía entre documentos:

| Prop | Qué controla | Ejemplo |
|---|---|---|
| `endpoint` | Endpoint del backend a consultar/enviar (`GET/POST/PATCH /api/{endpoint}`) | `"Orders"`, `"Invoices"`, `"PurchaseOrders"`, `"PurchaseInvoices"` |
| `tipoDocumento` | Etiqueta tipada (`OrdenVenta`, `FacturaVenta`, `OrdenCompra`, `FacturaProveedor`) declarada en `DocumentConfigProps` | — no se usa dentro de la lógica del propio formulario en el código leído; parece ser solo metadata para quien lo invoca |
| `titulo` | Encabezado visible del formulario | `"Factura de Ventas (OINV)"` |
| `headerExtraFields` | Campos de cabecera exclusivos de ese documento | Facturas: `FolioPrefixString`, `FolioNumber`, `GroupNum` |
| `lineColumns` | Columnas de la grilla de líneas, cada una con un `show(doc)` opcional para ocultar/mostrar según `DocType` | Compras oculta `ItemCode`/`Almacén` si `DocType` es de servicio |
| `copyFromSources` | Documentos origen habilitados para el botón "Copiar de" (ícono de portapapeles) | Facturas de Venta: Orden de Venta y Entrega; Facturas de Proveedor: Orden de Compra |
| `retencionConfig` / `detraccionConfig` | Solo presentes en `PurchaseInvoices.tsx` — habilitan los bloques de Retención (3%/6%) y Detracción (SUNAT) en el resumen de totales | No se pasan en Órdenes ni en Facturas de Venta |
| `onBuscarSocio`, `onBuscarArticulos`, `onCellSearch` | Callbacks que abren los `ModalSearchTemplate` de Socios, Artículos, Almacén y Código de Impuesto | Cada vista instancia sus propios modales y decide qué endpoint/filtro usar |

El cálculo de totales (subtotal, impuesto 18% fijo, retención, detracción, total general) vive dentro del propio `MarketingDocumentForm`, no en las vistas.

Los íconos de acción (búsqueda, copiar de, catálogo, eliminar línea) son SVG inline definidos en `src/components/ui/Icon.tsx` — no hay emojis ni dependencias externas de iconografía en el proyecto.

### Campo técnico en tooltip, no en el label

Cada `CampoConfig`/`HeaderExtraFieldConfig` de `genericHeaderFields` acepta un `dbField` (= su propio `name`, ya que ambos son literalmente el nombre del campo en `MarketingDocument`) que `FormattedField`/`SelectField` muestran como un ícono ⓘ junto al label; al pasar el mouse aparece el nombre técnico SAP (ej. `DocEntry`, `CardCode`). Antes el label concatenaba ambos textos ("Documento (DocEntry)"), lo que a veces partía el campo en dos líneas y deformaba la grilla — ver `FieldTooltip.tsx`.

### Campos de solo lectura (`readOnly` / `readOnlyOnUpdate`)

`CampoConfig` soporta dos flags que `MarketingDocumentForm` traduce a `mode="display"` (o `disabled` en los `SelectField`):

| Campo | Flag | Comportamiento |
|---|---|---|
| `DocEntry` | `readOnly: true` | Nunca editable (ni al crear ni al actualizar) — lo asigna SAP |
| `DocNum` | `readOnlyOnUpdate: true` | Editable al crear, bloqueado al actualizar |
| `CardCode` | `readOnlyOnUpdate: true` | Editable al crear, bloqueado al actualizar; además oculta el botón de búsqueda de socio cuando está bloqueado |

`readOnlyOnUpdate` se evalúa contra `isEditMode` (`!!docEntry`), definido dentro del propio `MarketingDocumentForm`.

## Flujo: Crear una Factura de Venta copiando una Orden

```mermaid
sequenceDiagram
  actor User as Usuario
  participant List as InvoicesList
  participant View as Invoices.tsx
  participant Form as MarketingDocumentForm
  participant Copy as CopyFromModal
  participant API as api.ts
  participant Backend as backend sales.py
  participant SAP as SAP Service Layer

  User->>List: /ventas/facturas → "Nueva Factura"
  List->>View: navigate("/ventas/facturas/mantenimiento")
  View->>Form: <MarketingDocumentForm endpoint="Invoices" copyFromSources=[Orden, Entrega] />
  Form->>API: GET /api/Currencies
  API->>Backend: fetch
  Backend->>SAP: GET Currencies
  SAP-->>Form: lista de monedas

  User->>Form: busca y selecciona Cliente (ícono de lupa)
  Form->>View: onBuscarSocio() abre ModalSearchTemplate(BusinessPartners)
  View-->>Form: setDoc({CardCode, CardName})

  User->>Form: clic "Copiar de" → "Orden de Venta"
  Form->>Copy: <CopyFromModal source={Orden} cardCode docType />
  Copy->>API: GET /api/Orders?filtro por CardCode/BaseType
  API->>Backend: fetch
  Backend->>SAP: GET Orders
  SAP-->>Copy: documentos abiertos del cliente
  User->>Copy: selecciona una orden
  Copy-->>Form: onConfirm(lines, sourceLabel)
  Note over Form: Si ya hay líneas, confirm() pregunta reemplazar o agregar
  Form->>Form: setDoc({DocumentLines: lines}) — cada línea trae BaseType/BaseEntry/BaseLine

  User->>Form: clic "Crear Documento"
  Form->>API: POST /api/Invoices (doc + DocumentLines, sin BaseRef)
  API->>Backend: fetch POST
  Backend->>SAP: POST Invoices (con líneas BaseEntry → SAP cierra la orden origen)
  SAP-->>Backend: 201 Created
  Backend-->>Form: ok
  Form-->>User: "Documento creado exitosamente en SAP"
```

El mismo patrón aplica a Facturas de Proveedor copiando desde Órdenes de Compra, solo cambian `endpoint` y `copyFromSources`.

## Árbol de Componentes

```
App.tsx (BrowserRouter)
└── / (ProtectedRoute → MainLayout)
    ├── /ventas
    │   ├── /ordenes            → OrdersList.tsx → ListViewTemplate → StatusBadge
    │   ├── /ordenes/mantenimiento → Orders.tsx → MarketingDocumentForm
    │   ├── /entrega             → stub "Entregas / Guías" (sin vista real, ver Hallazgos)
    │   └── /facturas
    │       ├── (lista)          → InvoicesList.tsx → ListViewTemplate → StatusBadge
    │       └── /mantenimiento   → Invoices.tsx → MarketingDocumentForm
    └── /compras
        ├── /ordenes            → PurchaseOrdersList.tsx → ListViewTemplate → StatusBadge
        ├── /ordenes/mantenimiento → PurchaseOrders.tsx → MarketingDocumentForm
        ├── /recepcion           → stub "Recepciones de Compra" (sin vista real, ver Hallazgos)
        └── /facturas
            ├── (lista)          → PurchaseInvoicesList.tsx → ListViewTemplate → StatusBadge
            └── /mantenimiento   → PurchaseInvoices.tsx → MarketingDocumentForm (+ Retención/Detracción)

MarketingDocumentForm.tsx
├── FormattedField.tsx / SelectField.tsx  (cabecera, con FieldTooltip por campo)
├── PrimaryButton.tsx / SecondaryButton.tsx (submit / cancelar)
├── Icon.tsx                               (íconos SVG: buscar, copiar, catálogo, eliminar)
├── PageLoader.tsx                         ("Cargando documento..." mientras hace fetch)
├── CopyFromModal.tsx                     (botón "Copiar de")
└── (por vista) ModalSearchTemplate.tsx ×4  (Socios, Artículos, Almacén, Código de Impuesto)
```

Cada vista de mantenimiento (`Orders`, `Invoices`, `PurchaseOrders`, `PurchaseInvoices`) se carga con `React.lazy()` desde `App.tsx`: el JS de un módulo no se descarga hasta que el usuario navega a él (ver `docs/index.md`).

## Archivos Clave

| Archivo | Ruta | Propósito |
|---|---|---|
| `MarketingDocumentForm.tsx` | `src/components/` | Formulario genérico: cabecera, grilla de líneas, totales, copiar-de, submit GET/POST/PATCH |
| `Orders.tsx` / `Invoices.tsx` | `src/views/ventas/` | Configuran el formulario para Órdenes y Facturas de venta |
| `PurchaseOrders.tsx` / `PurchaseInvoices.tsx` | `src/views/compras/` | Configuran el formulario para Compras; Facturas agrega retención/detracción |
| `OrdersList.tsx`, `InvoicesList.tsx`, `PurchaseOrdersList.tsx`, `PurchaseInvoicesList.tsx` | `src/views/ventas/`, `src/views/compras/` | Listados vía `ListViewTemplate`, con `StatusBadge` por estado del documento |
| `CopyFromModal.tsx` | `src/components/ui/` | Modal para copiar líneas desde un documento base (Orden→Entrega→Factura) |
| `ModalSearchTemplate.tsx` | `src/components/ui/` | Modal de búsqueda genérico reutilizado para Socios, Artículos, Almacenes, Códigos de Impuesto |
| `sapMarketing.ts` | `src/types/` | `MarketingDocument`, `DocumentLine`, `DocumentConfigProps`, `CopyFromSource`, `LineColumnConfig` (`key`/`name` tipados como `keyof DocumentLine`/`keyof MarketingDocument`, no `string` suelto) |
| `sunat.ts` | `src/utils/` | `DETRACCION_CODIGOS` (porcentajes SUNAT usados en Facturas de Proveedor) |
| `Icon.tsx` | `src/components/ui/` | Registro de íconos SVG inline (reemplaza los emojis que se usaban antes en botones y menú) |
| `FieldTooltip.tsx` | `src/components/ui/` | Ícono ⓘ con el nombre técnico SAP del campo, usado por `FormattedField`/`SelectField` |
| `errors.ts` | `src/utils/` | `getErrorMessage(err, fallback)` — evita `catch (err: any)` en cada formulario |
| `sales.py` / `purchases.py` | `mini-backend/routers/` | Endpoints REST que proxean a SAP Service Layer |

## Hallazgos (código tal cual está hoy, sin corregir)

- **`ventas/entrega` y `compras/recepcion` son stubs**: en `App.tsx` son componentes en línea que solo muestran un título ("Entregas / Guías" / "Recepciones de Compra"), sin listado ni formulario real todavía.
- **`DeliveryNotesList.tsx` existe pero no está enrutado**: el archivo `src/views/ventas/DeliveryNotesList.tsx` está escrito pero ninguna ruta en `App.tsx` lo importa o lo usa — no es alcanzable desde la navegación actual.
- El endpoint `PurchaseDeliveryNotes` (documentado en `mini-backend/docs/api-reference.md`) tampoco tiene vista de frontend correspondiente todavía.