npm package: @genzai_cloud/agent-db-architect
Description: Arquitecto experto de bases de datos PostgreSQL/Supabase especializado en mantener, extender y documentar modelos de datos para sistemas de inventario
Author: genzai_cloud
Latest version: 1.0.0

# Agente dbArchitect

> Arquitecto experto de bases de datos PostgreSQL/Supabase especializado en mantener, extender y documentar modelos de datos para sistemas de inventario

## Descripción General

Este agente especializado actúa como un arquitecto de bases de datos relacionales con más de 10 años de experiencia en PostgreSQL y Supabase. Su función principal es mantener, extender y documentar el modelo de datos del sistema de inventario para un centro de estética, asegurando que cada cambio sea coherente, bien documentado y fácil de implementar.

## Filosofía Central

### Regla de Oro
**Simplicidad Primero, Complejidad Solo Cuando Sea Necesaria**

### Enfoque
Este agente no sobrediseña. Aplica un enfoque pragmático centrado en resolver problemas reales del negocio. El modelo de datos evoluciona incrementalmente según necesidades comprobadas, no especulaciones. Cada cambio es no destructivo, está completamente documentado y sigue convenciones estrictas de diseño.

## Metodología

Este agente opera en **DOS MODOS**:

### Modo 1: Consultas Directas (Sin Fases)
Para preguntas que NO modifican el modelo:
- Explicar cómo funciona el modelo actual
- Proveer consultas SQL para casos específicos
- Optimizar queries existentes
- Explicar convenciones de diseño

**Resultado esperado**: Respuesta directa con ejemplos SQL

### Modo 2: Extensiones del Modelo (4 Fases)
Para cambios que SÍ modifican el modelo:

#### Fase 1: Análisis del Requerimiento
**Objetivo**: Comprender exactamente qué se necesita cambiar o agregar

**Resultado esperado**: Especificación clara y validada del cambio

#### Fase 2: Diseño de la Solución
**Objetivo**: Diseñar la arquitectura técnica completa

**Resultado esperado**: Diagramas ER, especificaciones detalladas, justificación de decisiones

#### Fase 3: Generación de Scripts
**Objetivo**: Crear scripts SQL listos para ejecutar

**Resultado esperado**: Scripts de migración no destructivos, funciones actualizadas, validaciones

#### Fase 4: Documentación y Entrega
**Objetivo**: Proveer documentación actualizada y artefactos finales

**Resultado esperado**: Documentación completa, schema de Prisma, checklist de validación

## Frameworks/Estructuras Incluidas

### Convenciones de Nombrado PostgreSQL

**Tablas**:
- Singular, snake_case
- Ejemplo: `producto`, `lote`, `movimiento`

**Campos**:
- snake_case descriptivos
- Ejemplo: `fecha_vencimiento`, `costo_unitario`

**Claves Primarias**:
- Siempre `id UUID PRIMARY KEY DEFAULT gen_random_uuid()`

**Claves Foráneas**:
- Formato: `{tabla}_id`
- Ejemplo: `producto_id`, `lote_id`

**Índices**:
- Formato: `idx_{tabla}_{campo(s)}`
- Ejemplo: `idx_lote_producto`, `idx_movimiento_fecha`

**Constraints**:
- Formato: `chk_{descripcion}`
- Ejemplo: `chk_cantidad_positiva`, `chk_disponible_no_negativo`

**Funciones**:
- Formato: `{verbo}_{sustantivo}`
- Ejemplo: `obtener_ipv`, `calcular_precio_con_descuento`

### Tipos de Datos Estándar

| Uso | Tipo |
|-----|------|
| Identificadores | `UUID` |
| Dinero (unitario) | `DECIMAL(10,2)` |
| Dinero (totales) | `DECIMAL(12,2)` |
| Cantidades | `INTEGER` |
| Porcentajes/Ratios | `DECIMAL(5,4)` |
| Fechas | `DATE` |
| Timestamps | `TIMESTAMPTZ` |
| Texto corto | `VARCHAR(n)` |
| Texto largo | `TEXT` |

### Principios de Integridad

```sql
-- Siempre RESTRICT, nunca CASCADE
REFERENCES producto(id) ON DELETE RESTRICT

-- Validar cantidades no negativas
CONSTRAINT chk_cantidad_positiva CHECK (cantidad > 0)

-- Timestamps en todas las tablas principales
created_at TIMESTAMPTZ DEFAULT NOW()
updated_at TIMESTAMPTZ DEFAULT NOW()
```

## Errores Comunes a Evitar

### Error 1: Usar CASCADE

**Problema**: Eliminar datos en cascada es peligroso en sistemas de inventario

**En vez de esto**:
```sql
REFERENCES producto(id) ON DELETE CASCADE
```

**Haz esto**:
```sql
REFERENCES producto(id) ON DELETE RESTRICT
```

### Error 2: Permitir Valores Negativos

**Problema**: Cantidades y montos negativos no tienen sentido de negocio

**En vez de esto**:
```sql
cantidad INTEGER NOT NULL
```

**Haz esto**:
```sql
cantidad INTEGER NOT NULL,
CONSTRAINT chk_cantidad_positiva CHECK (cantidad > 0)
```

### Error 3: No Usar COALESCE en Agregaciones

**Problema**: NULLs inesperados rompen cálculos

**En vez de esto**:
```sql
SUM(cantidad) AS total
```

**Haz esto**:
```sql
COALESCE(SUM(cantidad), 0)::BIGINT AS total
```

## Cómo Usar Este Agente

### Modo 1: Proyecto Claude (Recomendado)

1. **Crear Proyecto**
   - Ve a Claude.ai
   - Crea nuevo Proyecto Claude
   - Nombra: "DB Architect - Sistema Inventario"

2. **Agregar Instrucciones**
   - Agrega `prompt-principal.md` como instrucciones del proyecto

3. **Agregar Conocimiento**
   - Agrega todos los archivos `fase-*.md`
   - Agrega archivos del sistema:
     - `supabase_inventory_v1.2.sql`
     - `documentacion_inventario_v1.2.md`
     - `convenciones_diseno.md`

4. **Comenzar**
   - Abre chat del proyecto
   - Haz tu consulta o solicita un cambio
   - El agente identificará automáticamente el modo apropiado

### Modo 2: Consola Claude

1. **Copiar Contenido**
   - Copia contenido completo de `prompt-principal.md`
   - Copia archivos de fase relevantes
   - Copia archivos del sistema actual

2. **Nueva Conversación**
   - Pega el prompt principal
   - Proporciona contexto del sistema
   - Haz tu consulta

## Formato de Input

### Para Consultas Directas

**Ejemplos**:
- "¿Qué campos tiene la tabla lote?"
- "¿Cómo obtengo el IPV de hoy?"
- "Explícame cómo funciona FEFO"
- "Dame una query para productos por vencer"

### Para Extensiones del Modelo

**Mínimo requerido**:
- **Qué necesitas agregar/cambiar**: Descripción del cambio
- **Por qué lo necesitas**: Problema de negocio que resuelve

**Opcional pero útil**:
- Campos específicos que imaginas
- Reglas de negocio conocidas
- Consultas que harías con los nuevos datos

**Ejemplo de input**:
```
Necesito agregar una tabla de proveedores porque quiero saber de quién compré cada lote.

Campos que creo necesitar:
- Nombre del proveedor
- Teléfono
- Email

Consultas que quiero hacer:
- "¿De quién compré este lote?"
- "¿Cuánto le he comprado al proveedor X?"
```

## Formato de Output

### Modo Consulta Directa

```markdown
**[Respuesta concisa]**

Ejemplo:
```sql
SELECT * FROM tabla WHERE condicion;
```

[Explicación adicional si es necesario]
```

### Modo Extensión con Fases

El agente te guiará por 4 fases, solicitando aprobación en cada una:

1. **Fase 1**: Análisis del requerimiento con preguntas clarificadoras
2. **Fase 2**: Diseño técnico con diagramas ER y especificaciones
3. **Fase 3**: Scripts SQL completos y testeables
4. **Fase 4**: Documentación actualizada, Prisma schema, checklist

Al final recibes:
- Scripts SQL de migración
- Documentación actualizada del modelo
- Schema de Prisma (si aplica)
- Checklist de validación

## Agentes Complementarios

Este agente trabaja bien con:
- **asesorDocumentacion**: Para crear documentación técnica completa del sistema
- **Futuros agentes de backend**: Para implementar lógica de negocio sobre el modelo

**Flujo típico**:
```
[dbArchitect] → Diseña y migra BD
    ↓
[Backend Agent] → Implementa API sobre modelo
    ↓
[asesorDocumentacion] → Documenta sistema completo
```

## Ejemplos de Uso

### Caso 1: Consulta Simple sobre el Modelo

**Input**:
```
¿Cómo funciona el sistema de promociones en el inventario?
```

**Output esperado**:
```markdown
El sistema de promociones permite crear descuentos en lotes específicos:

**Tabla `promocion`**:
- Asociada a un `lote` específico (no a producto completo)
- Dos tipos de descuento:
  - `cut`: Monto fijo (ej: -$5)
  - `off`: Porcentaje (ej: 20%)
- Vigencia controlada con `fecha_inicio` y `fecha_fin`

**Ejemplo de uso**:
```sql
-- Crear promoción del 20% en un lote por vencer
INSERT INTO promocion (lote_id, tipo_descuento, valor_descuento, fecha_inicio, fecha_fin)
VALUES ('uuid-lote', 'off', 20.00, CURRENT_DATE, '2025-01-30');

-- Calcular precio con descuento
SELECT calcular_precio_con_descuento(25.00, 'off', 20);  -- Resultado: 20.00
```

**Beneficio**: Reduce mermas al liquidar productos próximos a vencer.
```

### Caso 2: Extensión del Modelo (Agregar Proveedores)

**Input**:
```
Necesito agregar proveedores al sistema para saber de quién compré cada lote.
```

**Output esperado** (resumido, el proceso completo tiene 4 fases):

**Fase 1 - Análisis**:
```markdown
Entiendo que necesitas registrar proveedores y relacionarlos con lotes.

Preguntas:
1. ¿Qué datos del proveedor necesitas? (nombre, teléfono, email, etc.)
2. ¿Todos los lotes deben tener proveedor?
3. ¿Qué consultas harás? (ej: total comprado por proveedor)
```

**Fase 2 - Diseño**:
```markdown
Propuesta: Tabla `proveedor` con relación N:1 desde `lote`

Diagrama ER:
[Muestra diagrama con la nueva tabla]

Especificaciones detalladas de campos, tipos, constraints...
```

**Fase 3 - Scripts**:
```sql
-- Script SQL completo de migración
CREATE TABLE proveedor (...);
ALTER TABLE lote ADD COLUMN proveedor_id ...;
-- etc.
```

**Fase 4 - Documentación**:
```markdown
Documentación actualizada del modelo
Schema de Prisma
Checklist de validación
Historial de versiones actualizado
```

### Caso 3: Optimización de Query

**Input**:
```
Esta query está lenta:
SELECT * FROM lote WHERE fecha_vencimiento <= CURRENT_DATE + INTERVAL '30 days'
```

**Output esperado**:
```markdown
La query está filtrando por `fecha_vencimiento`, que ya tiene índice (`idx_lote_vencimiento`).

**Optimización sugerida**:
```sql
-- En lugar de SELECT *, especifica campos necesarios
SELECT id, producto_id, disponible, fecha_vencimiento, costo_unitario
FROM lote
WHERE fecha_vencimiento IS NOT NULL
  AND fecha_vencimiento BETWEEN CURRENT_DATE AND CURRENT_DATE + INTERVAL '30 days'
  AND disponible > 0
ORDER BY fecha_vencimiento ASC;
```

**Por qué es mejor**:
- Evita SELECT * (menos datos transferidos)
- Agrega `disponible > 0` (ignora lotes vacíos)
- Usa BETWEEN en lugar de <= (más claro para el optimizador)
- ORDER BY aprovecha el índice

**Verificar plan de ejecución**:
```sql
EXPLAIN ANALYZE [query optimizada];
```
```

## Limitaciones Conocidas

- **Especializado en un sistema**: Este agente está optimizado para el sistema de inventario específico del centro de estética. Para otros dominios, necesitarías adaptarlo.
- **No ejecuta scripts**: El agente genera scripts SQL pero no los ejecuta. Debes ejecutarlos manualmente en Supabase.
- **PostgreSQL/Supabase específico**: Las convenciones y funciones son para PostgreSQL. No aplican directamente a MySQL, SQL Server, etc.
- **Requiere contexto**: Para extensiones complejas, necesita acceso a la documentación actual del sistema.

## Contribuir

¿Tienes ideas para mejorar este agente?
- Lee [CONTRIBUTING.md](../CONTRIBUTING.md)
- Revisa [Specs/Maintenance/](../Specs/Maintenance/) para guías
- Propón mejoras vía Pull Request

## Versión

**Versión actual**: v1.0.0
**Última actualización**: 2026-01-15
**Modelo base del sistema**: v1.2 (con promociones por lote)

## Licencia

MIT License (igual que el proyecto genzai-agents)

---

**Nota**: Este agente está diseñado para **mantener y extender modelos de datos de inventario en PostgreSQL/Supabase**. No está diseñado para diseñar modelos desde cero, migrar entre diferentes BD, o trabajar con sistemas no relacionales.