# US-{MODULO}-{NNN}: {Titulo de la Historia}

> **INSTRUCCIONES:** Copiar este template para cada historia de usuario.
> Eliminar esta seccion antes de guardar.

---

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-{MODULO}-{NNN} |
| **Modulo** | {MGN-NNN / MAI-NNN} |
| **Epica** | {Nombre de la epica} |
| **Prioridad** | {P0 / P1 / P2 / P3} |
| **Story Points** | {1 / 2 / 3 / 5 / 8 / 13} |
| **Sprint** | Sprint {N} |
| **Estado** | {Backlog / Ready / In Progress / Done} |
| **Autor** | {nombre} |
| **Fecha** | {YYYY-MM-DD} |

---

## Historia de Usuario

**Como** {rol de usuario}
**Quiero** {accion o funcionalidad deseada}
**Para** {beneficio o valor que obtiene}

### Contexto

{Descripcion adicional del contexto de negocio. Por que es importante esta historia?}

---

## Criterios de Aceptacion

### Escenario 1: {Nombre del escenario - Happy Path}

```gherkin
Feature: {Nombre de la funcionalidad}

  Scenario: {Descripcion del escenario}
    Given {contexto inicial / precondiciones}
      And {otra precondicion si aplica}
    When {accion que realiza el usuario}
      And {otra accion si aplica}
    Then {resultado esperado}
      And {otro resultado si aplica}
```

### Escenario 2: {Escenario alternativo}

```gherkin
  Scenario: {Descripcion}
    Given {contexto}
    When {accion}
    Then {resultado}
```

### Escenario 3: {Manejo de errores}

```gherkin
  Scenario: {Error handling}
    Given {contexto que causa error}
    When {accion}
    Then {mensaje de error mostrado}
      And {sistema permanece en estado consistente}
```

---

## Mockups / Wireframes

### Pantalla Principal

> Incluir referencia a Figma o descripcion visual

```
+------------------------------------------------------------------+
|  Header: {Titulo de la pantalla}                    [Boton Accion]|
+------------------------------------------------------------------+
|                                                                   |
|  +-------------------------------------------------------------+ |
|  |  Componente 1                                               | |
|  |  - Elemento A                                               | |
|  |  - Elemento B                                               | |
|  +-------------------------------------------------------------+ |
|                                                                   |
|  +-------------------------------------------------------------+ |
|  |  Tabla / Lista                                              | |
|  |  | Col 1 | Col 2 | Col 3 | Acciones |                       | |
|  |  | dato  | dato  | dato  | [E] [X]  |                       | |
|  +-------------------------------------------------------------+ |
|                                                                   |
|  [Cancelar]                                    [Guardar Borrador] |
|                                                         [Guardar] |
+------------------------------------------------------------------+
```

### Estados de UI

| Estado | Comportamiento |
|--------|----------------|
| Loading | Mostrar skeleton/spinner |
| Empty | Mensaje "No hay {recursos}" + CTA |
| Error | Toast con mensaje de error |
| Success | Toast de confirmacion |

---

## Flujo de Usuario

```mermaid
flowchart TD
    A[Usuario accede a pantalla] --> B{Tiene permisos?}
    B -->|No| C[Mostrar error 403]
    B -->|Si| D[Cargar lista de recursos]
    D --> E{Hay datos?}
    E -->|No| F[Mostrar estado vacio]
    E -->|Si| G[Mostrar tabla]
    G --> H[Usuario selecciona accion]
    H --> I{Tipo de accion}
    I -->|Crear| J[Abrir formulario]
    I -->|Editar| K[Cargar datos y abrir formulario]
    I -->|Eliminar| L[Confirmar y eliminar]
    J --> M[Validar y guardar]
    K --> M
    M -->|Exito| N[Toast success + Refrescar lista]
    M -->|Error| O[Toast error]
```

---

## Notas Tecnicas

### API Endpoints Involucrados

| Metodo | Endpoint | Proposito |
|--------|----------|-----------|
| GET | `/api/v1/{recursos}` | Listar |
| POST | `/api/v1/{recursos}` | Crear |
| PATCH | `/api/v1/{recursos}/:id` | Actualizar |
| DELETE | `/api/v1/{recursos}/:id` | Eliminar |

### Componentes Frontend

| Componente | Tipo | Descripcion |
|------------|------|-------------|
| `{Nombre}Page` | Page | Pagina principal |
| `{Nombre}Table` | Component | Tabla de datos |
| `{Nombre}Form` | Component | Formulario crear/editar |
| `{Nombre}Modal` | Component | Modal de confirmacion |

### Store (Zustand)

```typescript
interface {Nombre}Store {
  // Estado
  items: {Nombre}[];
  loading: boolean;
  error: string | null;
  selectedItem: {Nombre} | null;

  // Acciones
  fetchAll: () => Promise<void>;
  create: (dto: Create{Nombre}Dto) => Promise<void>;
  update: (id: string, dto: Update{Nombre}Dto) => Promise<void>;
  remove: (id: string) => Promise<void>;
  setSelected: (item: {Nombre} | null) => void;
}
```

### Validaciones Frontend

| Campo | Regla | Mensaje |
|-------|-------|---------|
| `name` | required, min 3 | "Nombre es requerido (min 3 caracteres)" |
| `email` | valid email | "Email invalido" |
| `{campo}` | {regla} | "{mensaje}" |

---

## Dependencias

### Historias Bloqueantes

| ID | Historia | Estado |
|----|----------|--------|
| US-{MOD}-{NNN} | {Titulo} | {Estado} |

### Historias Relacionadas

| ID | Historia | Relacion |
|----|----------|----------|
| US-{MOD}-{NNN} | {Titulo} | {Tipo: depende/habilita/relacionada} |

---

## Trazabilidad

### Requerimientos

| ID | Requerimiento |
|----|---------------|
| RF-{MOD}-{NNN} | {Titulo del requerimiento} |

### Casos de Prueba

| ID | Caso de Prueba | Tipo |
|----|----------------|------|
| TC-{MOD}-{NNN} | {Descripcion} | {Unit/Integration/E2E} |

---

## Estimacion por Capa

| Capa | Story Points | Horas Estimadas | Notas |
|------|--------------|-----------------|-------|
| Database | {N} | {N}h | {consideraciones} |
| Backend | {N} | {N}h | {consideraciones} |
| Frontend | {N} | {N}h | {consideraciones} |
| Testing | {N} | {N}h | {consideraciones} |
| **Total** | **{N}** | **{N}h** | |

---

## Definition of Done

- [ ] Codigo implementado y revisado (code review)
- [ ] Tests unitarios pasando (>80% coverage)
- [ ] Tests de integracion pasando
- [ ] Documentacion actualizada
- [ ] Swagger actualizado
- [ ] Sin errores de lint
- [ ] Funcionalidad verificada en ambiente de desarrollo
- [ ] Criterios de aceptacion cumplidos
- [ ] Product Owner aprobo

---

## Notas y Decisiones

### Decisiones Tomadas

- {Decision 1}: {Razon}
- {Decision 2}: {Razon}

### Riesgos Identificados

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| {Riesgo 1} | {Alta/Media/Baja} | {Alto/Medio/Bajo} | {Accion} |

### Preguntas Abiertas

- [ ] {Pregunta 1}
- [ ] {Pregunta 2}

---

## Historial de Cambios

| Version | Fecha | Autor | Cambios |
|---------|-------|-------|---------|
| 1.0 | {YYYY-MM-DD} | {nombre} | Creacion inicial |

---

## Aprobaciones

| Rol | Nombre | Fecha | Aprobado |
|-----|--------|-------|----------|
| Tech Lead | | | [ ] |
| Product Owner | | | [ ] |
| QA Lead | | | [ ] |

---
*Template version 1.0 - ERP Suite*