Ciclo Comercial — Flujo Completo

Tipo: Flujo end-to-end Estado: implementado (MVP) Fecha: 2026-03-25 Implementado en: feature/crm-ciclo-comercial-mvp

---

Descripción

Flujo completo del ciclo de vida comercial: desde el registro de la oportunidad en CRM hasta el cobro de la venta facturada. Atraviesa 4 módulos: Comercial/CRM, Producción, Administración y Tesorería.

Toda oportunidad comercial se registra como un registro CRM Comercial, independientemente de su origen. Si proviene de una licitación, se marca con el flag es_licitacion en el CRM (con anexo futuro a datos detallados de licitación).

El documento central del flujo es la Nota de Venta, que nace al confirmar la venta y recorre todo el ciclo con estados que cada módulo actualiza.

---

Diagrama general del ciclo

Ver diagrama detallado de cada fase en su respectivo archivo.

flowchart LR
    subgraph COMERCIAL ["Fase 1: Comercial/CRM"]
        Reg[Registro CRM<br/>Comercial] --> Flags["flags: es_licitacion<br/>tiene_poliza"]
        Flags --> Venta{¿Venta<br/>concretada?}
        Venta -->|Sí| NV[Nota de Venta<br/>pedido_confirmado]
    end

    subgraph PRODUCCION ["Fase 2: Producción"]
        Fab[Fabricación<br/>+ versionado]
        Fab --> Disp[disponible]
    end

    subgraph ADMIN ["Fase 3: Administración"]
        TipoOp{Tipo<br/>operación}
        TipoOp --> Fact[Facturación<br/>Final]
    end

    subgraph TESO ["Fase 4: Tesorería"]
        Cobro[Proceso<br/>de Cobro]
        Cobro --> Cobrada[cobrada]
    end

    NV -->|A1: requiere fabricación| Fab
    NV -->|A2: sin fabricación| TipoOp
    Disp -->|B1| TipoOp
    Fact -->|C1 Finanzas| Cobro

---

Fases del ciclo

Fase	Módulo	Documento principal	Doc entrada	Doc salida
1	Comercial/CRM	flujo-comercial-process	Inicio	A1 Producción / A2 Administración
2	Producción	flujo-produccion-process	A1 desde Comercial o pedido directo	B1 Administración
3	Administración	flujo-administracion-process	A2 Comercial / B1 Producción	C1 Finanzas (Tesorería)
4	Tesorería	flujo-tesoreria-ventas-process	C1 Finanzas	Fin (cobrada)

---

Documento central

→ Nota de Venta — estados desde pedido_confirmado hasta cobrada

---

Todos los documentos del ciclo

Comercial/CRM

Documento	Tipo	Descripción
flujo-comercial-process	process	Flujo unificado: Registro CRM Comercial → venta
licitacion-resource	resource	Flag licitación en CRM Comercial + modelo futuro
poliza-seguro-resource	resource	Póliza Seguro Garantía (TBD)
nota-pedido-resource	resource	Nota de Pedido (Comercial)
extension-comercial	resource	CRM tipo Comercial (rename desde industrial)
extension-produccion	resource	CRM tipo Producción (trazabilidad)
analisis-requerimientos-nv	resource	Analisis completo de requerimientos NV (fuente del cliente)
comisiones-resource	resource	Comisiones concesionarios + vendedores

Producción

Documento	Tipo	Descripción
flujo-produccion-process	process	Fabricación, loop cambios, versionado
nota-pedido-produccion-resource	resource	Nota de Pedido con versionado
orden-trabajo-resource	resource	Orden de Trabajo
proceso-productivo-resource	resource	Procesos, sectores, tiempos
configuracion	índice	Sectores, responsables, artículos

Administración

Documento	Tipo	Descripción
flujo-administracion-process	process	Tres tipos de operación → facturación final
documentos-generados	resource	Formatos de Conf NP (RE-COM003), NV (RE-COM004), Remito y Factura

Tesorería

Documento	Tipo	Descripción
flujo-tesoreria-ventas-process	process	Cobro, retenciones, comisiones

Transversal

Documento	Tipo	Descripción
nota-venta-resource	resource	Documento central: estados multi-módulo
entidades-comerciales	resource	Mapa de entidades: concesionario, cliente, contacto, proveedor. ERD y relaciones.
nota-venta-desde-crm-process	process	Creación y derivación de la NV
preguntas-abiertas	índice	Índice consolidado de preguntas abiertas y TBDs del ciclo

---

Cambios mandatory pendientes

Cambio	Documento	Estado
Rename tipo CRM industrial → comercial	extension-comercial	Pendiente de implementar Implementado (MVP)

---

Preguntas abiertas globales

Índice consolidado: Ver preguntas-abiertas.md para el listado completo de todas las preguntas abiertas del ciclo comercial, organizadas por tema.

Pregunta	Documentada en
¿Stock disponible omite Producción? No. Ciclo completo siempre.	flujo-produccion, nota-venta
¿Una OT o varias por pedido?	orden-trabajo
¿Campo contacto en CRM Producción?	extension-produccion
¿Póliza es entidad propia o campo? Solo flag tiene_poliza en CRM Comercial.	poliza-seguro
¿Qué son GEN_FA y GEN_FR? Son tres orígenes de facturación (C1, GEN_FA, GEN_FR) que convergen al mismo proceso de cobro.	flujo-tesoreria

---

Aclaraciones de reuniones de negocio

Reglas confirmadas y matices identificados en reuniones con el cliente. Fuentes: "Modificaciones luego de Analizar el DFD.docx" y "Cambios por nuevas consultas del 27-11-2025.docx" (~Nov 2025).

#	Concepto	Decisión	Tipo	Documentado en
1	NV generada por usuario CRM comercial	Confirmado	Core	flujo-comercial-process
2	Docs ISO (Confirmación NP + Pedido Producción) generados por el sistema	Confirmado	Core	flujo-comercial-process, nota-pedido-resource
3	Modificaciones post-confirmación: ¿quién modifica y cómo?	Confirmado: Solo vendedor o Admin. Reimprimir Pedido + email. Producción pasiva.	Core	flujo-comercial-process
4	Rol de Producción: ¿pasiva o con versionado?	Confirmado: Producción es actor pasivo. No versiona ni modifica.	Core	flujo-produccion-process
5	NV por ítem: flexible (1:1 o N:1 configurable)	Confirmado	Config	nota-venta-resource
6	Factura:NV = 1:N	Confirmado	Core	nota-venta-resource
7	Estado en_negro para ventas informales	Confirmado	Core	nota-venta-resource
8	Retenciones: mecanismo formal + override manual	Confirmado	Core	flujo-tesoreria, nota-venta-resource
9	Repuesto: PV específico es config de empresa	Confirmado	Config	flujo-administracion-process
10	Entrega máquina (N° serie, etc.): extensión maquinaria	Confirmado	Extensión	flujo-administracion-process
11	Póliza: baja progresiva por entrega	Confirmado	Core (licitaciones)	poliza-seguro-resource, flujo-administracion-process
12	Comisiones/bonificaciones: fuera de scope, solo informes. Las bonificaciones de precio de la NV son N dinámicas encadenadas (tabla nota_venta_bonificacion), no 3 porcentajes fijos.	Confirmado	Exclusión / Core	flujo-tesoreria, nota-venta-resource
13	Licitación unificada: todo registro es CRM Comercial. Si proviene de licitación, se marca con flag es_licitacion en el CRM. Modelo detallado de licitación diferido como anexo futuro.	Confirmado	Config	licitacion-resource, extension-comercial
14	¿Es Licitación? en Administración: se hereda automáticamente del flag es_licitacion del CRM de origen. No es verificación manual.	Confirmado	Config	flujo-administracion-process
15	GEN_FA, GEN_FR y C1 son las tres entradas al cobro (tres orígenes de facturación desde Administración); el proceso de cobro es idéntico para las tres	Confirmado	Core	flujo-tesoreria
16	Stock no omite Producción	Confirmado	Core	nota-venta-resource
17	Estados NV pueden retroceder	Confirmado	Core	nota-venta-resource
18	Pedido:Producción es 1:1	Confirmado	Core	nota-pedido-resource
19	Ítems NP vienen de presupuesto CRM Los ítems de NP provienen del catálogo de productos de Ventas. NP es independiente del budget CRM (sin FK).	Actualizado 2026-03-31	Core	nota-pedido-resource, entidades-comerciales
20	Póliza solo flag en esta etapa	Confirmado	Config	poliza-seguro-resource
21	Docs ISO (NV, Conf NP, Pedido Prod) deben imprimirse	Confirmado	Core	flujo-comercial-process, nota-pedido-resource
22	NP y NV: modificables en cualquier estado → genera revisión. Numeración NP-XXXX Rev.0N / NV-XXXX Rev.0N.	Confirmado 2026-03-31	Core	nota-pedido-resource, nota-venta-resource
23	Modalidades A/B/C/D: campo declarativo (clasificador) en MVP. Sin lógica asociada. Extensible en v2.	Confirmado 2026-03-31	Config	nota-pedido-resource, nota-venta-resource
24	importe_a_facturar se define al crear la NV. Puede actualizarse (genera revisión).	Confirmado 2026-03-31	Core	nota-venta-resource
25	Adquirentes sin registro: alta automática en ordcon al persistir la NV.	Confirmado 2026-03-31	Core	nota-venta-resource
26	concesionario_id en NV → FK a ordcon, siempre requerido. Recibe el cliente_id de la NP (puede ser concesionario o cliente directo). No se exige que sea concesionario. Sin FK formal ordcon↔cpdprov en esta etapa.	Confirmado 2026-03-31	Core	entidades-comerciales, nota-venta-resource
27	NP y NV viven en Modules/Crm/ como subdominios del ciclo CRM.	Confirmado 2026-03-31	Arquitectura	—
28	NV → Facturación: genera prefa directamente (flujo propio, paralelo al budget→prefa existente).	Confirmado 2026-03-31	Core	nota-venta-resource

---

Estado MVP

Implementado en feature/crm-ciclo-comercial-mvp:

Componente	Repo	Estado
Migraciones (ALTERs + 6 tablas nuevas)	migrations/	✅ Implementado
Módulo NP — backend (Models→Routes + tests)	bautista-backend/	✅ Implementado
Módulo NV — backend (Models→Routes + tests)	bautista-backend/	✅ Implementado
Test integración NP ciclo completo	bautista-backend/	✅ Implementado
Frontend NP — types, schema, service, hooks, components	bautista-app/	✅ Implementado
Frontend NV — types, schema, service, hooks, components	bautista-app/	✅ Implementado
Integración cards Tab 2 CrmRecordFormActions	bautista-app/	✅ Implementado
PDF RE-COM003 (confirmación NP)	informes/	✅ Implementado
PDF RE-COM004 (nota de venta)	informes/	✅ Implementado

Estados MVP de Nota de Pedido: borrador, confirmada, cancelada.

Estados MVP de Nota de Venta: solo pedido_confirmado y cancelada. Los estados en_fabricacion, disponible, facturado, cobrada son seteados por otros módulos (post-MVP).

Fuera de scope MVP (post-MVP):

• USD / tipo de cambio / dólar diferido
• Estados NV: en_produccion, disponible, con_cambios, entregado, facturado, cobrado
• NV → prefa (flujo de facturación desde NV — arquitectura preparada, no activada)
• Relación NP/NV ↔ budget/presupuesto CRM

---

Endpoints disponibles (MVP)

Nota de Pedido — Modules/Crm/

Método	Ruta	Descripción
POST	/mod-crm/nota-pedido	Crear NP (estado inicial: borrador)
GET	/mod-crm/nota-pedido	Listar NP (filtros: crm_record_id, estado)
GET	/mod-crm/nota-pedido/{id}	Detalle NP
PUT	/mod-crm/nota-pedido/{id}	Actualizar NP (solo estado borrador)
DELETE	/mod-crm/nota-pedido/{id}	Soft delete (solo estado borrador)
POST	/mod-crm/nota-pedido/{id}/confirmar	Confirmar NP (borrador → confirmada)
GET	/mod-crm/nota-pedido/{id}/revisiones	Historial de versiones

Nota de Venta — Modules/Crm/

Método	Ruta	Descripción
POST	/mod-crm/nota-venta	Crear NV desde NP confirmada (estado: pedido_confirmado)
GET	/mod-crm/nota-venta	Listar NV
GET	/mod-crm/nota-venta/{id}	Detalle NV
PUT	/mod-crm/nota-venta/{id}	Actualizar NV (genera nueva versión)
POST	/mod-crm/nota-venta/{id}/cancelar	Cancelar NV

PDFs (informes/ port 9999)

Código	Nombre	Disponible para
405	RE-COM003 Confirmación Nota de Pedido	NP en estado confirmada
406	RE-COM004 Nota de Venta	NV en estado pedido_confirmado

Referencia técnica completa: specs SDD en openspec/changes/crm-ciclo-comercial-mvp/specs/crm/