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

-- 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:

REFERENCES producto(id) ON DELETE CASCADE

Haz esto:

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:

cantidad INTEGER NOT NULL

Haz esto:

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:

SUM(cantidad) AS total

Haz esto:

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

**[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:

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:

-- Script SQL completo de migración
CREATE TABLE proveedor (...);
ALTER TABLE lote ADD COLUMN proveedor_id ...;
-- etc.

Fase 4 - Documentación:

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:

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:

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.