# US-MGN005-005: Gestionar Categorias Jerarquicas

## Identificacion

| Campo | Valor |
|-------|-------|
| **ID** | US-MGN005-005 |
| **Modulo** | MGN-005 Catalogs |
| **Sprint** | Sprint 3 |
| **Prioridad** | P1 - Alta |
| **Story Points** | 5 |
| **Estado** | Ready |
| **RF Relacionado** | RF-CATALOG-005 |
| **Fecha** | 2025-12-05 |

---

## Historia de Usuario

**Como** usuario del sistema
**Quiero** crear y gestionar categorias jerarquicas
**Para** organizar productos, servicios y otros elementos en estructuras de arbol

---

## Descripcion

El sistema debe soportar categorias con multiples niveles de profundidad (jerarquia padre-hijo). Cada categoria puede tener subcategorias, formando un arbol. Se usan para clasificar productos, documentos, y otros elementos.

### Contexto

- Estructura de arbol multinivel
- Tipos de categoria: products, services, documents, expenses
- Navegacion breadcrumb
- Path materializado para consultas eficientes

---

## Criterios de Aceptacion

### Escenario 1: Listar categorias como arbol

```gherkin
Given un usuario con permiso "catalogs.categories.read"
When accede a GET /api/v1/catalogs/categories?type=products
Then el sistema responde con status 200
  And retorna estructura de arbol con categorias raiz
  And cada categoria incluye children[] con sus hijos
```

### Escenario 2: Listar categorias planas

```gherkin
Given un usuario con permiso "catalogs.categories.read"
When accede a GET /api/v1/catalogs/categories?type=products&flat=true
Then retorna lista plana de todas las categorias
  And cada categoria incluye path completo (ej: "Electrónica > Computadoras > Laptops")
```

### Escenario 3: Crear categoria raiz

```gherkin
Given un usuario con permiso "catalogs.categories.manage"
When envia POST /api/v1/catalogs/categories
  | code | "electronics" |
  | name | "Electrónica" |
  | type | "products" |
  | parentId | null |
Then el sistema responde con status 201
  And la categoria se crea en nivel 1
  And path = "electronics"
```

### Escenario 4: Crear subcategoria

```gherkin
Given categoria padre "Electrónica" con id "uuid-parent"
When envia POST /api/v1/catalogs/categories
  | code | "computers" |
  | name | "Computadoras" |
  | type | "products" |
  | parentId | "uuid-parent" |
Then la categoria se crea en nivel 2
  And path = "electronics.computers"
```

### Escenario 5: Mover categoria

```gherkin
Given categoria "Laptops" hija de "Computadoras"
When envia PATCH /api/v1/catalogs/categories/laptops
  | parentId | "uuid-tablets" |
Then "Laptops" se mueve bajo "Tablets"
  And se actualizan los paths de Laptops y sus descendientes
```

### Escenario 6: Eliminar categoria con hijos

```gherkin
Given categoria "Electrónica" con subcategorias
When intenta eliminar "Electrónica"
Then el sistema responde con status 400
  And el mensaje indica "Categoria tiene subcategorias"
  And sugiere eliminar hijos primero o mover categoria
```

### Escenario 7: Obtener breadcrumb

```gherkin
Given categoria "Laptops" con path "electronics.computers.laptops"
When accede a GET /api/v1/catalogs/categories/laptops?include=breadcrumb
Then retorna la categoria con array breadcrumb:
  | [0] | Electrónica |
  | [1] | Computadoras |
  | [2] | Laptops |
```

### Escenario 8: Buscar en categorias

```gherkin
Given categorias existentes
When envia GET /api/v1/catalogs/categories?search=laptop
Then retorna categorias cuyo nombre contenga "laptop"
  And incluye el path completo para contexto
```

---

## Mockup / Wireframe

```
+------------------------------------------------------------------+
|  CATEGORIAS                                   [+ Nueva Categoria] |
+------------------------------------------------------------------+
| [Tipo: Productos v]  [Buscar...]                                 |
+------------------------------------------------------------------+

Vista Arbol:
+------------------------------------------------------------------+
| [-] Electrónica                                                   |
|     [-] Computadoras                                              |
|         [+] Laptops (3 productos)                                |
|         [+] Desktops (5 productos)                               |
|     [+] Telefonos                                                 |
|     [+] Accesorios                                                |
| [-] Hogar                                                         |
|     [+] Muebles                                                   |
|     [+] Decoracion                                                |
| [+] Ropa                                                          |
+------------------------------------------------------------------+

Modal: Nueva Categoria
+------------------------------------------------------------------+
| NUEVA CATEGORIA                                             [X]  |
+------------------------------------------------------------------+
| Tipo*                                                            |
| [Productos v]                                                    |
|                                                                  |
| Categoria Padre                                                  |
| [Seleccionar... v]                                               |
| > Electrónica                                                    |
|   > Computadoras                                                 |
|   > Telefonos                                                    |
| > Hogar                                                          |
|                                                                  |
| Codigo*                  | Nombre*                                |
| [laptops          ]      | [Laptops              ]               |
|                                                                  |
| Descripcion                                                      |
| [________________________________]                               |
|                                                                  |
|                               [Cancelar]  [=== Guardar ===]     |
+------------------------------------------------------------------+
```

---

## Notas Tecnicas

### API Endpoints

| Metodo | Path | Descripcion |
|--------|------|-------------|
| GET | /catalogs/categories | Listar (arbol o plano) |
| GET | /catalogs/categories/:id | Detalle con breadcrumb |
| POST | /catalogs/categories | Crear |
| PATCH | /catalogs/categories/:id | Actualizar/mover |
| DELETE | /catalogs/categories/:id | Eliminar |

### Estructura LTREE

```sql
-- Path materializado para consultas eficientes
path LTREE

-- Obtener todos los descendientes
SELECT * FROM categories WHERE path <@ 'electronics';

-- Obtener ancestros
SELECT * FROM categories WHERE path @> 'electronics.computers.laptops';
```

---

## Definicion de Done

- [ ] CRUD categorias con jerarquia
- [ ] Path materializado (LTREE)
- [ ] Vista arbol y plana
- [ ] Mover categoria (reparent)
- [ ] Validacion eliminar con hijos
- [ ] Breadcrumb
- [ ] Componente CategoryTree
- [ ] Componente CategorySelect (con arbol)
- [ ] Tests unitarios
- [ ] Documentacion Swagger

---

## Dependencias

### Requiere

| Item | Descripcion |
|------|-------------|
| Extension LTREE | PostgreSQL |
| Tabla categories | Con path y parent_id |

### Bloquea

| Item | Descripcion |
|------|-------------|
| Productos | Clasificacion |
| Documentos | Organizacion |
| Gastos | Clasificacion contable |

---

## Historial

| Version | Fecha | Autor | Cambios |
|---------|-------|-------|---------|
| 1.0 | 2025-12-05 | Requirements-Analyst | Creacion inicial |
