workspace-v1/orchestration/directivas/simco/SIMCO-CREAR.md

SIMCO: CREAR ARCHIVO

Versión: 1.0.0 Fecha: 2025-12-08 Aplica a: TODO agente que vaya a crear un archivo nuevo Prioridad: OBLIGATORIA

---

RESUMEN EJECUTIVO

Antes de crear cualquier archivo, VERIFICA que no exista y sigue las convenciones.

---

CHECKLIST RÁPIDO

ANTES DE CREAR
├── [ ] 0. 🆕 Verificar @CATALOG_INDEX → ¿Existe funcionalidad en catálogo?
│         Si existe → Seguir @REUTILIZAR en lugar de crear nuevo
├── [ ] 1. Verificar @INVENTORY → ¿Ya existe objeto similar en proyecto?
├── [ ] 2. Buscar con grep/find → ¿Archivo duplicado?
├── [ ] 3. Identificar ubicación correcta según tipo
└── [ ] 4. Leer template/referencia si existe

DURANTE CREACIÓN
├── [ ] 5. Seguir convenciones de nomenclatura
├── [ ] 6. Incluir encabezado estándar
└── [ ] 7. Documentar inline (comentarios)

DESPUÉS DE CREAR
├── [ ] 8. Validar localmente (compilar/ejecutar)
├── [ ] 9. Actualizar inventario correspondiente
└── [ ] 10. Actualizar traza correspondiente

---

FASE 0: VERIFICAR CATÁLOGO (NUEVO - OBLIGATORIO)

0.1 Consultar Catálogo de Funcionalidades

ANTES de crear cualquier funcionalidad común, verificar si existe en el catálogo:

# Buscar en índice del catálogo
grep -i "{funcionalidad}" @CATALOG_INDEX

# Funcionalidades catalogadas:
# - auth (login, registro, JWT, OAuth)
# - session-management (sesiones concurrentes, dispositivos)
# - rate-limiting (throttle, 429)
# - notifications (email, push, in-app)
# - multi-tenancy (tenant, RLS)
# - feature-flags (toggles dinámicos)
# - websocket (realtime, streaming)
# - payments (Stripe, suscripciones)

Si encuentra en @CATALOG:

🛑 NO CREAR NUEVO - REUTILIZAR DEL CATÁLOGO

1. Ir a: core/catalog/{funcionalidad}/
2. Leer: README.md (descripción y trade-offs)
3. Seguir: IMPLEMENTATION.md (pasos detallados)
4. Copiar: _reference/ (código base)
5. Adaptar: configuración al proyecto actual

Ver directiva completa: @REUTILIZAR (SIMCO-REUTILIZAR.md)

Si NO encuentra en @CATALOG:

✅ Continuar con Fase 1 (crear nuevo)

---

FASE 1: ANTES DE CREAR

1.1 Verificación Anti-Duplicación (OBLIGATORIO)

Consultar inventario:

# Verificar en inventario maestro
grep -i "{nombre_objeto}" @INVENTORY

# Si es base de datos
grep -i "{nombre_tabla}" @INV_DB

# Si es backend
grep -i "{nombre_entity}" @INV_BE

# Si es frontend
grep -i "{nombre_componente}" @INV_FE

Buscar en código:

# Buscar archivos similares
find apps/ -name "*{nombre}*" -type f

# Buscar contenido similar
grep -rn "CREATE TABLE.*{nombre}" @DDL_ROOT
grep -rn "class {Nombre}" @BACKEND
grep -rn "export.*{Nombre}" @FRONTEND

Si encuentras duplicado:

🛑 DETENER INMEDIATAMENTE

Reportar:
- Objeto existente: {ubicación}
- Objeto que iba a crear: {ubicación propuesta}
- Pregunta: ¿Modificar existente o crear nuevo con diferente nombre?

NO CONTINUAR sin clarificación.

1.2 Identificar Ubicación Correcta

Tipo de Archivo	Ubicación (@ALIAS)	Patrón de Nombre
Tabla DDL	@DDL/{schema}/tables/	{NN}-{nombre}.sql
Function DDL	@DDL/{schema}/functions/	{nombre}.sql
Trigger DDL	@DDL/{schema}/triggers/	trg_{tabla}_{accion}.sql
Seed Dev	@SEEDS_DEV	{NN}-{nombre}.sql
Entity Backend	@BACKEND/{modulo}/entities/	{nombre}.entity.ts
Service Backend	@BACKEND/{modulo}/services/	{nombre}.service.ts
Controller Backend	@BACKEND/{modulo}/controllers/	{nombre}.controller.ts
DTO Backend	@BACKEND/{modulo}/dto/	{accion}-{nombre}.dto.ts
Componente Frontend	@FRONTEND/{app}/components/	{Nombre}.tsx
Página Frontend	@FRONTEND/{app}/pages/	{Nombre}Page.tsx
Hook Frontend	@FRONTEND/{app}/hooks/	use{Nombre}.ts

1.3 Leer Referencias

Antes de crear, lee un archivo similar existente:

# Para DDL: leer tabla existente del mismo schema
cat @DDL/{schema}/tables/01-*.sql | head -100

# Para Entity: leer entity existente del módulo
cat @BACKEND/{modulo}/entities/*.entity.ts | head -100

# Para Componente: leer componente similar
cat @FRONTEND/{app}/components/*.tsx | head -100

Extraer de la referencia:

• Formato de encabezado
• Estilo de comentarios
• Convenciones de imports
• Estructura general

---

FASE 2: DURANTE CREACIÓN

2.1 Encabezados Estándar

Para archivos SQL:

-- ============================================================================
-- {Tipo}: {nombre}
-- Schema: {schema}
-- Descripción: {descripción breve}
-- Autor: {Agente}
-- Fecha: {YYYY-MM-DD}
-- Dependencias: {lista o "Ninguna"}
-- ============================================================================

Para archivos TypeScript (Backend):

/**
 * {Nombre} - {descripción breve}
 *
 * @description {descripción detallada}
 * @module {módulo}
 * @author {Agente}
 * @date {YYYY-MM-DD}
 * @see {referencia a DDL o especificación}
 */

Para archivos TSX (Frontend):

/**
 * {NombreComponente}
 *
 * @description {descripción del componente}
 * @module {app/módulo}
 * @author {Agente}
 * @date {YYYY-MM-DD}
 */

2.2 Convenciones de Nomenclatura

SQL (PostgreSQL):

-- Schemas: snake_case
CREATE SCHEMA auth_management;

-- Tablas: snake_case, plural
CREATE TABLE users, student_progress, badges;

-- Columnas: snake_case
user_id, first_name, created_at

-- Índices: idx_{tabla}_{columna(s)}
CREATE INDEX idx_users_email ON users(email);

-- Foreign Keys: fk_{tabla}_to_{tabla_ref}
CONSTRAINT fk_students_to_users

-- Checks: chk_{tabla}_{columna}
CONSTRAINT chk_users_status

-- Triggers: trg_{tabla}_{accion}
CREATE TRIGGER trg_users_updated

TypeScript (Backend):

// Entities: PascalCase + Entity suffix
UserEntity, StudentProgressEntity, BadgeEntity

// Services: PascalCase + Service suffix
UserService, GamificationService

// Controllers: PascalCase + Controller suffix
UserController, AuthController

// DTOs: PascalCase + Dto suffix
CreateUserDto, UpdateUserDto

// Métodos: camelCase
createUser(), findById()

// Constantes: UPPER_SNAKE_CASE
MAX_LOGIN_ATTEMPTS, DEFAULT_PAGE_SIZE

TypeScript (Frontend):

// Componentes: PascalCase
UserProfile, LoginForm, Dashboard

// Hooks: use + PascalCase
useUser, useAuth, useDashboard

// Stores: camelCase + Store
userStore, authStore

// Types/Interfaces: PascalCase
User, AuthState, DashboardProps

2.3 Documentación Inline

OBLIGATORIO incluir:

• Comentarios en lógica compleja
• JSDoc/TSDoc en funciones públicas
• COMMENT ON en tablas y columnas SQL
• Descripción de props en componentes

---

FASE 3: DESPUÉS DE CREAR

3.1 Validación Local (OBLIGATORIO)

Para SQL:

# Ejecutar DDL
psql -d {DB_NAME} -f {archivo.sql}

# Verificar estructura
psql -d {DB_NAME} -c "\d {schema}.{tabla}"

Para Backend:

cd @BACKEND_ROOT
npm run build    # DEBE pasar
npm run lint     # DEBE pasar

Para Frontend:

cd @FRONTEND_ROOT
npm run build    # DEBE pasar
npm run lint     # DEBE pasar

3.2 Actualizar Inventario (OBLIGATORIO)

Agregar entrada en @INVENTORY:

# Ejemplo para tabla
database:
  schemas:
    {schema}:
      tables:
        - name: {nombre_tabla}
          file: @DDL/{schema}/tables/{archivo}.sql
          created_by: {Agente}
          fecha: {YYYY-MM-DD}
          status: "✅ Completo"

# Ejemplo para entity
backend:
  modules:
    {modulo}:
      entities:
        - name: {NombreEntity}
          file: @BACKEND/{modulo}/entities/{archivo}.ts
          related_table: {schema}.{tabla}
          created_by: {Agente}
          fecha: {YYYY-MM-DD}
          status: "✅ Completo"

3.3 Actualizar Traza (OBLIGATORIO)

Agregar entrada en traza correspondiente:

## [{ID}] Crear {nombre}

**Fecha:** {YYYY-MM-DD HH:MM}
**Estado:** ✅ Completado
**Agente:** {Nombre-Agente}

### Archivos Creados
- `{ruta_completa_archivo}`

### Validaciones
- [x] Compilación exitosa
- [x] Inventario actualizado
- [x] Sin duplicados

### Notas
{observaciones relevantes}

---

ERRORES COMUNES Y CÓMO EVITARLOS

Error	Causa	Solución
Duplicado creado	No verificó inventario	SIEMPRE verificar @INVENTORY primero
Ubicación incorrecta	No consultó alias	Usar tabla de ubicaciones arriba
Nombre incorrecto	No siguió convenciones	Revisar sección 2.2
Build falla	No validó localmente	SIEMPRE ejecutar build antes de reportar
Inventario desactualizado	Olvidó actualizar	Incluir en checklist final

---

REFERENCIAS

• Catálogo de funcionalidades: @CATALOG (CONSULTAR PRIMERO)
• Reutilización: @REUTILIZAR (SIMCO-REUTILIZAR.md)
• Convenciones completas: @DIRECTIVAS/ESTANDARES-NOMENCLATURA-BASE.md
• Validación: @VALIDAR (SIMCO-VALIDAR.md)
• Documentación: @DOCUMENTAR (SIMCO-DOCUMENTAR.md)
• Aliases: @ALIASES

---

Versión: 1.0.0 | Sistema: SIMCO | Mantenido por: Tech Lead