# Cheatsheet de Símbolos de Diagramas

> Referencia rápida para PMs. No necesitas memorizar todos los símbolos —necesitas saber cuáles existen para usarlos cuando corresponda.

---

## 1. Flowchart — Símbolos ISO 5807

| Símbolo | Nombre | Significado | Ejemplo de Uso |
|---------|--------|-------------|----------------|
| ┌──────────┐ │  Inicio  │ └──────────┘ | **Terminator** | Inicio o fin del flujo. Siempre hay exactamente 1 inicio. Puede haber múltiples fines (una salida feliz, una salida por error). | "El usuario solicita reembolso" / "Fin del flujo" |
| ┌──────────┐ │  Proceso │ └──────────┘ | **Proceso / Acción** | Una acción ejecutada por el sistema o el usuario. Debe ser un verbo en imperativo. | "Enviar email de confirmación" / "Guardar en base de datos" |
| ┌─────┴─────┐ │ ¿Condición?│ └─────┬─────┘ | **Decisión** | Una bifurcación condicional. Siempre tiene 2+ salidas etiquetadas (Sí/No, o valores específicos). | "¿Usuario tiene permisos?" → Sí / No |
| ┌──────────┐ │  /  │ │  Datos  │ └──────────┘ | **Datos / E/S** | Entrada o salida de datos. Leer de un archivo, mostrar un mensaje, consultar una API. | "Consultar pasarela de pago" / "Mostrar mensaje de error" |
| ┌──────────┐ │  │ ║ │ │  │ ║ │ └──────────┘ | **Subproceso** | Un proceso definido en otro diagrama. Útil para dividir flujos complejos. | "Procesar pago" (definido en otro flowchart) |
| ─────> | **Flecha de flujo** | Dirección del flujo. Siempre etiquetada si sale de una decisión. | — |

### Reglas Prácticas para PMs

1. **Un inicio, múltiples fines.** El flujo siempre arranca en un solo punto. Puede terminar de varias formas (éxito, error, cancelación).
2. **Toda decisión tiene 2+ salidas etiquetadas.** Si ves una decisión sin etiquetas, está incompleta.
3. **No cruces flechas.** Si necesitas cruzar flechas, tu diagrama es demasiado complejo. Divídelo en subprocesos.
4. **Un nodo, una acción.** No pongas dos verbos en el mismo nodo. "Validar email y enviar confirmación" → divídelo en dos nodos.
5. **Caben en una pantalla.** Si necesitas scroll vertical u horizontal, refactoriza.

### Ejemplo de Aplicación

```
┌──────────────────┐
│ Usuario solicita  │
│ reembolso         │
└────────┬─────────┘
         │
         v
┌──────────────────┐    No    ┌──────────────────────┐
│ ¿Dentro de 30     │────────>│ Mostrar:              │
│ días de compra?   │         │ "Período de reembolso │
│                   │         │  expirado"            │
└────────┬──────────┘         └──────────────────────┘
         │ Sí
         v
┌──────────────────┐    No    ┌──────────────────────┐
│ ¿Producto         │────────>│ Mostrar:              │
│ elegible?         │         │ "Producto no elegible" │
└────────┬──────────┘         └──────────────────────┘
         │ Sí
         v
┌──────────────────┐
│ Procesar reembolso│
│ vía pasarela      │
└────────┬──────────┘
         │
         v
┌──────────────────┐    Sí    ┌──────────────────────┐
│ ¿Error en         │────────>│ Notificar a soporte   │
│ pasarela?         │         │ técnico + log         │
└────────┬──────────┘         └──────────────────────┘
         │ No
         v
┌──────────────────┐
│ Mostrar confirmación│
│ + email             │
└────────────────────┘
```

---

## 2. State Diagram — Notación UML

| Símbolo | Nombre | Significado |
|---------|--------|-------------|
| ┌──────────┐ │  Estado  │ └──────────┘ | **Estado** | Una condición estable del objeto en un momento dado. El objeto permanece aquí hasta que ocurre un evento. |
| ──> | **Transición** | Movimiento de un estado a otro. Debe estar etiquetada con el evento que la causa. |
| ──[Evento]─> | **Transición etiquetada** | El evento que causa el cambio de estado. Formato: `evento(parámetros) [condición] / acción`. |
| ┌──────────┐ │ ──── │ │ ──── │ └──────────┘ | **Estado Inicial** | Pseudo-estado donde nace el objeto. Representado como un círculo sólido. |
| ┌──────────┐ │ ──── │ │ ──── │ └──────────┘ | **Estado Final** | Pseudo-estado donde el objeto termina su vida. Representado como un círculo sólido con borde. |

### Convenciones para PMs

- **Solo dibujas estados, no acciones.** "Enviar email" no es un estado, es una acción que ocurre durante una transición.
- **Nombra estados como adjetivos o participios:** Pendiente, Aprobado, Rechazado, En Proceso, Bloqueado.
- **Cada transición tiene un evento:** No digas "cambia a Aprobado". Di "el revisor hace clic en Aprobar".
- **Documenta transiciones inválidas explícitamente:** "De Aprobado no se puede volver a Pendiente" es información valiosa para el equipo técnico.

### Ejemplo: Estados de una Orden

```
                  ┌──────────────┐
                  │  PENDIENTE   │
                  └──────┬───────┘
                         │
             ┌───────────┼───────────┐
             │           │           │
             v           v           v
      ┌──────────┐ ┌──────────┐ ┌──────────┐
      │ PAGADA   │ │          │ │          │
      │          │ │CANCELADA │ │ RECHAZADA│
      └─────┬────┘ └──────────┘ └──────────┘
            │
            v
      ┌──────────┐
      │ ENVIADA  │
      └─────┬────┘
            │
            v
      ┌──────────┐
      │ ENTREGADA│
      └──────────┘
```

### Tabla de Transiciones (para acompañar el diagrama)

| Estado Actual | Evento | Condición | Siguiente Estado | Acción |
|--------------|--------|-----------|-----------------|--------|
| Pendiente | Usuario paga | Pago exitoso | Pagada | Enviar email factura |
| Pendiente | Usuario cancela | — | Cancelada | — |
| Pendiente | Timeout 30 min | — | Rechazada | Liberar inventario |
| Pagada | Admin despacha | Stock disponible | Enviada | Enviar tracking |
| Pagada | Admin reembolsa | — | Cancelada | Procesar reembolso |
| Enviada | Courier confirma | — | Entregada | Enviar encuesta |

---

## 3. Sequence Diagram — Lifelines y Mensajes

| Símbolo | Nombre | Significado | Sintaxis Mermaid |
|---------|--------|-------------|------------------|
| ─── | **Lifeline** | Línea vertical que representa la vida de un actor/sistema durante la interacción. Los bloques rectangulares son "activaciones" (período en que el actor está activo). | `participant Actor` |
| ──> | **Mensaje asíncrono** | Mensaje donde el emisor no espera respuesta inmediata. El emisor continúa su ejecución. | `A->>B: Mensaje` |
| ──>> | **Mensaje síncrono** | Mensaje donde el emisor espera una respuesta. Se representa con flecha llena. | `A->>B: Llamada` |
| - - >> | **Respuesta** | Línea punteada que devuelve el control al emisor. | `B-->>A: Respuesta` |
| ┌──────────┐ │ │ │ │ └──────────┘ | **Activación** | El rectángulo sobre la lifeline indica el período en que el actor está procesando. | Automático en Mermaid |

### Reglas para PMs

1. **Cada lifeline es un actor o sistema independiente.** No mezcles "Base de Datos" con "Backend" —son dos lifelines distintas si se comunican por red.
2. **El orden vertical ES tiempo.** Arriba = antes, abajo = después. No dibujes mensajes fuera de orden cronológico.
3. **No necesitas todos los detalles técnicos.** Un sequence diagram de alto nivel tiene 3-5 lifelines y 5-10 mensajes.
4. **Si hay 2+ sistemas externos, el sequence diagram es obligatorio.** Sin él, el equipo no entiende quién llama a quién ni en qué orden.

### Ejemplo: Pago con Stripe

```mermaid
sequenceDiagram
    participant Usuario
    participant Frontend
    participant Backend
    participant Stripe
    participant DB

    Usuario->>Frontend: Clic en "Pagar"
    Frontend->>Backend: POST /api/checkout
    Backend->>Stripe: Create PaymentIntent
    Stripe-->>Backend: client_secret
    Backend-->>Frontend: { clientSecret, publicKey }
    Frontend->>Stripe: confirmCardPayment
    Stripe-->>Frontend: PaymentResult
    Frontend->>Backend: POST /api/confirm
    Backend->>DB: Guardar orden
    DB-->>Backend: OK
    Backend-->>Frontend: 200
    Frontend-->>Usuario: "Pago exitoso"
```

### Lo que el Diagrama Revela

- **Timing:** ¿El frontend espera sincrónicamente la respuesta del backend?
- **Acoplamiento:** ¿Frontend habla directo con Stripe o todo pasa por backend?
- **Consistencia:** ¿Qué pasa si Stripe confirma pero el backend falla al guardar?
- **Manejo de error:** ¿Dónde se captura el error si Stripe rechaza la tarjeta?

---

## 4. Mermaid.js — Plantillas Rápidas

### Flowchart

```mermaid
graph TD
    A[Inicio] --> B{Condición}
    B -->|Sí| C[Acción 1]
    B -->|No| D[Acción 2]
    C --> E[Fin Feliz]
    D --> F[Fin Error]
```

```mermaid
graph LR
    A[Paso 1] --> B[Paso 2]
    B --> C{Paso 3?}
    C -->|Sí| D[Paso 4]
    C -->|No| E[Paso 5]
```

### State Diagram

```mermaid
stateDiagram-v2
    [*] --> EstadoA
    EstadoA --> EstadoB: Evento 1
    EstadoA --> EstadoC: Evento 2
    EstadoB --> EstadoD: Evento 3
    EstadoC --> EstadoD: Evento 4
    EstadoD --> [*]
```

### Sequence Diagram

```mermaid
sequenceDiagram
    participant A
    participant B
    participant C

    A->>B: Mensaje síncrono
    B-->>A: Respuesta
    A->>C: Mensaje asíncrono
    C-->>A: Callback
```

---

## 5. Tabla de Decisión: ¿Qué Diagrama Usar?

| Situación | Diagrama | Herramienta |
|-----------|----------|-------------|
| "El usuario hace clic aquí, luego pasa esto, luego esto otro..." | Flowchart | Mermaid.js |
| "La orden puede estar en estos estados..." | State Diagram | Mermaid.js |
| "El frontend llama al backend, el backend llama a Stripe..." | Sequence Diagram | Draw.io |
| "Si el cliente es de LATAM y tiene más de 50 users y es anual..." | Decision Tree | Excalidraw |
| "El proceso involucra a Ventas, Soporte, y el Cliente..." | BPMN / Swimlane | Draw.io |
| "No sé qué servicios hay ni cómo se conectan" | C4 Model (Context) | Draw.io |

---

## 6. Checklist Rápido de Inmunización Visual

Antes de compartir tu spec con el equipo técnico, verifica:

- [ ] El flowchart tiene: 1 inicio, 1+ fines, decisiones etiquetadas, ramas de error.
- [ ] El state diagram tiene: estado inicial, estados intermedios, estado final, todas las transiciones documentadas.
- [ ] El sequence diagram tiene: todos los actores/sistemas involucrados, orden cronológico correcto.
- [ ] No hay nodos desconectados ni flechas sin destino.
- [ ] El diagrama se entiende sin leer el spec (pruébalo con un compañero).

---

*Referencia rápida — Módulo 15, Bootcamp Product Operator*