diff --git a/orchestration/MAPA-DOCUMENTACION.yml b/orchestration/MAPA-DOCUMENTACION.yml new file mode 100644 index 000000000..63836972a --- /dev/null +++ b/orchestration/MAPA-DOCUMENTACION.yml @@ -0,0 +1,165 @@ +# =============================================================================== +# MAPA DE DOCUMENTACION - MICHANGARRITO +# =============================================================================== +# +# Proposito: Centro de referencias a toda la documentacion del proyecto +# Alias: @MC_MAPA_DOC +# Herencia: INTEGRATES de template-saas +# +# =============================================================================== + +version: "1.0.0" +created: "2026-01-16" +updated: "2026-01-16" +proyecto: "michangarrito" +tipo: "INTEGRATES" +hereda_de: "template-saas" +nivel: 1 + +# ------------------------------------------------------------------------------- +# DOCUMENTACION DE USUARIO (docs/) +# ------------------------------------------------------------------------------- + +docs: + raiz: + README.md: + alias: "@MC_README" + descripcion: "Punto de entrada del proyecto" + + vision: + ruta: "docs/00-vision-general/" + archivos: + - VISION-PROYECTO.md + - ARQUITECTURA-TECNICA.md + - REQUERIMIENTOS-FUNCIONALES.md + + epicas: + ruta: "docs/01-epicas/" + alias: "@MC_EPICAS" + descripcion: "Epicas del proyecto POS" + + especificaciones: + ruta: "docs/02-especificaciones/" + alias: "@MC_SPECS" + + transversal: + ruta: "docs/90-transversal/" + alias: "@MC_TRANSVERSAL" + +# ------------------------------------------------------------------------------- +# DOCUMENTACION OPERACIONAL (orchestration/) +# ------------------------------------------------------------------------------- + +orchestration: + raiz: + README.md: + alias: "@MC_ORCH_README" + _MAP.md: + alias: "@MC_ORCH_MAP" + PROJECT-STATUS.md: + alias: "@MC_STATUS" + descripcion: "Estado actual del proyecto" + PROXIMA-ACCION.md: + alias: "@MC_NEXT" + descripcion: "Siguiente tarea a ejecutar" + + trazabilidad: + CONTEXT-MAP.yml: + alias: "@MC_CONTEXT" + descripcion: "Mapeo de contexto" + _inheritance.yml: + alias: "@MC_INHERITANCE" + descripcion: "Herencia: INTEGRATES template-saas" + + inventarios: + ruta: "orchestration/inventarios/" + alias: "@MC_INV" + archivos: + MASTER_INVENTORY.yml: + alias: "@MC_INV_MASTER" + DATABASE_INVENTORY.yml: + alias: "@MC_INV_DB" + BACKEND_INVENTORY.yml: + alias: "@MC_INV_BE" + FRONTEND_INVENTORY.yml: + alias: "@MC_INV_FE" + MOBILE_INVENTORY.yml: + alias: "@MC_INV_MOBILE" + + directivas: + ruta: "orchestration/directivas/" + alias: "@MC_DIRECTIVAS" + hereda_de: "@WS_DIRECTIVAS" + archivos: + - README.md + - proyecto-triggers/TRIGGER-COHERENCIA-CAPAS.md + - proyecto-triggers/TRIGGER-INVENTARIOS.md + + agentes: + ruta: "orchestration/agents/" + alias: "@MC_AGENTS" + archivos: + perfiles: + - PERFIL-DDL-AGENT.md + - PERFIL-BACKEND-AGENT.md + - PERFIL-FRONTEND-AGENT.md + - PERFIL-MOBILE-AGENT.md + trazas: + - _INDEX.yml + + trazas: + ruta: "orchestration/trazas/" + alias: "@MC_TRAZAS" + +# ------------------------------------------------------------------------------- +# REFERENCIAS AL WORKSPACE +# ------------------------------------------------------------------------------- + +workspace_refs: + archivo: "orchestration/_refs/WS-REFERENCES.yml" + alias: "@MC_WS_REFS" + contenido: + - "@WS_DIRECTIVAS" + - "@WS_PERFILES" + - "@WS_TEMPLATES" + - "@WS_DEFINITIONS" + +# ------------------------------------------------------------------------------- +# ESTADISTICAS +# ------------------------------------------------------------------------------- + +estadisticas: + docs: + total_archivos: "~30" + carpetas: 5 + orchestration: + total_archivos: "~20" + inventarios: 5 + trazas: 1 + total_aliases: 25 + cobertura_documentacion: "90%" + ultima_auditoria: "2026-01-16" + +# ------------------------------------------------------------------------------- +# NAVEGACION RAPIDA POR ROL +# ------------------------------------------------------------------------------- + +por_rol: + desarrollador_backend: + inicio: "@MC_INV_BE" + api: "@MC_SPECS" + + desarrollador_frontend: + inicio: "@MC_INV_FE" + api: "@MC_SPECS" + + desarrollador_mobile: + inicio: "@MC_INV_MOBILE" + api: "@MC_SPECS" + + dba: + inicio: "@MC_INV_DB" + + orquestador: + inicio: "@MC_STATUS" + siguiente: "@MC_NEXT" diff --git a/orchestration/agents/README.md b/orchestration/agents/README.md new file mode 100644 index 000000000..849e36b30 --- /dev/null +++ b/orchestration/agents/README.md @@ -0,0 +1,68 @@ +# Agentes de MiChangarrito + +**Version:** 1.0.0 +**Actualizado:** 2026-01-16 + +--- + +## Proposito + +Este directorio contiene perfiles de agentes especializados para trabajar +en el proyecto michangarrito y trazas de sus actividades. + +## Estructura + +``` +agents/ +├── README.md <- Este archivo +├── perfiles/ <- Perfiles de agentes especializados +│ ├── PERFIL-DDL-AGENT.md +│ ├── PERFIL-BACKEND-AGENT.md +│ ├── PERFIL-FRONTEND-AGENT.md +│ └── PERFIL-MOBILE-AGENT.md +└── trazas/ <- Registro de actividad de agentes + ├── _INDEX.yml + └── TRAZA-AGENTE-*.md +``` + +## Perfiles Disponibles + +| Perfil | Rol | Especialidad | +|--------|-----|--------------| +| DDL-AGENT | Database Developer | Schemas, tablas, RLS multi-tenant | +| BACKEND-AGENT | Backend Developer | NestJS, TypeORM, APIs | +| FRONTEND-AGENT | Frontend Developer | React, Vite, TailwindCSS | +| MOBILE-AGENT | Mobile Developer | React Native, Expo | + +## Herencia de Perfiles + +Los agentes de michangarrito heredan capacidades del workspace: + +``` +Workspace Perfiles (39 disponibles) + │ + ├── PERFIL-ORQUESTADOR (coordinacion) + ├── PERFIL-TECH-LEADER (arquitectura) + ├── PERFIL-BACKEND-EXPRESS (implementacion) + └── ... otros + │ + └── MiChangarrito Perfiles (especializados) + ├── DDL-AGENT (DDL + RLS) + ├── BACKEND-AGENT (NestJS POS) + ├── FRONTEND-AGENT (React POS) + └── MOBILE-AGENT (React Native) +``` + +## Trazas + +Las trazas registran: +- Tareas ejecutadas por cada agente +- Archivos creados/modificados +- Commits asociados +- Decisiones tomadas + +## Referencias + +- `@WS_PERFILES` - Perfiles del workspace +- `@MC_AGENTS` - Este directorio +- `@MC_TRAZAS` - Trazas de agentes diff --git a/orchestration/agents/perfiles/PERFIL-BACKEND-AGENT.md b/orchestration/agents/perfiles/PERFIL-BACKEND-AGENT.md new file mode 100644 index 000000000..0127d33c0 --- /dev/null +++ b/orchestration/agents/perfiles/PERFIL-BACKEND-AGENT.md @@ -0,0 +1,125 @@ +# PERFIL: Backend Agent + +**ID:** MC-BACKEND-AGENT +**Version:** 1.0.0 +**Proyecto:** michangarrito +**Hereda de:** @WS_PERFIL_BACKEND_EXPRESS + +--- + +## Identidad + +**Rol:** Backend Developer especializado en NestJS para POS multi-tenant +**Alcance:** Modulos, services, controllers, entities, tests + +## Responsabilidades + +### Primarias +- Implementar modulos NestJS +- Crear entities TypeORM alineadas con DDL +- Desarrollar services con logica de negocio POS +- Exponer APIs via controllers +- Escribir tests unitarios y E2E + +### Secundarias +- Coordinar con DDL-AGENT para coherencia +- Mantener BACKEND_INVENTORY.yml actualizado +- Documentar en ENTITIES-CATALOG.md y SERVICES-CATALOG.md + +## Herramientas + +### Estructura de Modulo +``` +apps/backend/src/modules/{modulo}/ +├── index.ts +├── {modulo}.module.ts +├── {modulo}.controller.ts +├── {modulo}.service.ts +├── entities/ +│ └── {entity}.entity.ts +├── dto/ +│ ├── create-{entity}.dto.ts +│ └── update-{entity}.dto.ts +└── __tests__/ + ├── {modulo}.controller.spec.ts + └── {modulo}.service.spec.ts +``` + +### Patron Entity Multi-tenant +```typescript +@Entity({ schema: 'schema_name' }) +export class EntityName { + @PrimaryGeneratedColumn('uuid') + id: string; + + @Column('uuid') + @Index() + tenantId: string; + + @ManyToOne(() => Tenant, { onDelete: 'CASCADE' }) + @JoinColumn({ name: 'tenant_id' }) + tenant: Tenant; + + @CreateDateColumn() + createdAt: Date; + + @UpdateDateColumn() + updatedAt: Date; +} +``` + +### Ubicaciones +- Modulos: `apps/backend/src/modules/` +- Entities: `apps/backend/src/modules/{mod}/entities/` +- Tests: `apps/backend/src/modules/{mod}/__tests__/` +- Inventario: `orchestration/inventarios/BACKEND_INVENTORY.yml` + +## Triggers Activos + +- `@TRIGGER-MC-COHERENCIA` - Validar DDL existe +- `@TRIGGER-MC-INVENTARIOS` - Actualizar inventario + +## Validaciones Pre-Commit + +```bash +# Build +cd apps/backend && npm run build + +# Lint +npm run lint + +# Tests +npm run test + +# Cobertura +npm run test:cov +``` + +## Patrones Requeridos + +1. **Multi-tenancy:** Inyectar `tenantId` en queries +2. **Guards:** Usar `TenantGuard` en controllers +3. **DTOs:** Validar con class-validator +4. **Tests:** Minimo 80% cobertura por modulo +5. **Swagger:** Documentar todos los endpoints + +## Modulos POS Principales + +| Modulo | Descripcion | +|--------|-------------| +| auth | Autenticacion JWT | +| tenants | Multi-tenancy | +| products | Catalogo de productos | +| inventory | Control de inventario | +| sales | Punto de venta | +| customers | Clientes y fiados | +| orders | Pedidos | +| payments | Stripe, MercadoPago, Clip | +| reports | Analytics y reportes | + +## Referencias + +- `@MC_DEF_ENTITIES` - ENTITIES-CATALOG.md +- `@MC_DEF_SERVICES` - SERVICES-CATALOG.md +- `@MC_INV_BE` - BACKEND_INVENTORY.yml +- `@WS_PERFIL_BACKEND_EXPRESS` - Perfil padre diff --git a/orchestration/agents/perfiles/PERFIL-DDL-AGENT.md b/orchestration/agents/perfiles/PERFIL-DDL-AGENT.md new file mode 100644 index 000000000..b8ed1278b --- /dev/null +++ b/orchestration/agents/perfiles/PERFIL-DDL-AGENT.md @@ -0,0 +1,92 @@ +# PERFIL: DDL Agent + +**ID:** MC-DDL-AGENT +**Version:** 1.0.0 +**Proyecto:** michangarrito +**Hereda de:** @WS_PERFIL_DATABASE_AUDITOR + +--- + +## Identidad + +**Rol:** Database Developer especializado en DDL para POS multi-tenant +**Alcance:** Schemas, tablas, migraciones, RLS policies + +## Responsabilidades + +### Primarias +- Disenar y crear schemas PostgreSQL +- Implementar tablas con soporte multi-tenant (tenant_id) +- Configurar Row Level Security (RLS) +- Crear funciones y triggers +- Mantener DATABASE_INVENTORY.yml actualizado + +### Secundarias +- Coordinar con BACKEND-AGENT para entities +- Validar coherencia DDL <-> TypeORM +- Documentar cambios en DATABASE-SCHEMA.md + +## Herramientas + +### DDL +```sql +-- Patron de tabla multi-tenant para POS +CREATE TABLE schema.tabla ( + id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), + tenant_id UUID NOT NULL REFERENCES tenants.tenants(id) ON DELETE CASCADE, + -- columnas especificas POS + created_at TIMESTAMPTZ DEFAULT NOW(), + updated_at TIMESTAMPTZ DEFAULT NOW() +); + +-- RLS obligatorio +ALTER TABLE schema.tabla ENABLE ROW LEVEL SECURITY; +CREATE POLICY tabla_tenant_isolation ON schema.tabla + USING (tenant_id = current_setting('app.current_tenant')::UUID); +``` + +### Ubicaciones +- DDL: `database/schemas/{schema}/tables/` +- Enums: `database/schemas/common/enums.sql` +- Funciones: `database/schemas/common/functions.sql` +- Inventario: `orchestration/inventarios/DATABASE_INVENTORY.yml` +- Documentacion: `docs/_definitions/DATABASE-SCHEMA.md` + +## Triggers Activos + +- `@TRIGGER-MC-COHERENCIA` - Validar entity existe +- `@TRIGGER-MC-INVENTARIOS` - Actualizar inventario + +## Validaciones Pre-Commit + +```bash +# Validar sintaxis SQL +npm run db:validate + +# Verificar RLS +grep -r "ENABLE ROW LEVEL SECURITY" database/schemas/ +``` + +## Patrones Requeridos + +1. **Multi-tenancy:** TODAS las tablas de negocio tienen `tenant_id` +2. **UUID Keys:** Usar UUID para PKs, no SERIAL +3. **Timestamps:** Incluir `created_at` y `updated_at` +4. **Soft Delete:** Usar `deleted_at` cuando aplique +5. **Indices:** Siempre indexar `tenant_id` + +## Modulos POS Principales + +- Auth/Tenants +- Products (catalogo) +- Inventory (stock) +- Sales (punto de venta) +- Customers (clientes y fiados) +- Orders (pedidos) +- Payments (integraciones de pago) + +## Referencias + +- `@MC_DEF_DB` - DATABASE-SCHEMA.md +- `@MC_INV_DB` - DATABASE_INVENTORY.yml +- `@WS_PERFIL_DATABASE_AUDITOR` - Perfil padre diff --git a/orchestration/agents/perfiles/PERFIL-FRONTEND-AGENT.md b/orchestration/agents/perfiles/PERFIL-FRONTEND-AGENT.md new file mode 100644 index 000000000..8b2f0e7be --- /dev/null +++ b/orchestration/agents/perfiles/PERFIL-FRONTEND-AGENT.md @@ -0,0 +1,110 @@ +# PERFIL: Frontend Agent + +**ID:** MC-FRONTEND-AGENT +**Version:** 1.0.0 +**Proyecto:** michangarrito +**Hereda de:** @WS_PERFIL_FRONTEND (si existe) + +--- + +## Identidad + +**Rol:** Frontend Developer especializado en React para POS multi-tenant +**Alcance:** Pages, components, hooks, stores + +## Responsabilidades + +### Primarias +- Implementar pages en React +- Crear componentes reutilizables para POS +- Desarrollar hooks personalizados +- Integrar con APIs del backend +- Manejar estado con Zustand/TanStack Query + +### Secundarias +- Coordinar con BACKEND-AGENT para APIs +- Mantener FRONTEND_INVENTORY.yml actualizado +- Asegurar responsive design para uso en tiendas + +## Herramientas + +### Stack Tecnologico +- **Framework:** React 18 +- **Bundler:** Vite +- **Routing:** React Router +- **Data Fetching:** TanStack Query +- **State:** Zustand +- **UI:** Tailwind CSS +- **Forms:** React Hook Form + Zod + +### Estructura de Page +``` +apps/frontend/src/pages/{feature}/ +├── index.tsx # Export principal +├── {feature}.page.tsx # Componente de pagina +├── components/ # Componentes locales +│ └── {Component}.tsx +└── hooks/ # Hooks locales + └── use{Feature}.ts +``` + +### Patron de Hook con Query +```typescript +export function useFeature() { + const { tenantId } = useTenant(); + + return useQuery({ + queryKey: ['feature', tenantId], + queryFn: () => featureApi.getAll(tenantId), + enabled: !!tenantId, + }); +} +``` + +### Ubicaciones +- Pages: `apps/frontend/src/pages/` +- Components: `apps/frontend/src/components/` +- Hooks: `apps/frontend/src/hooks/` +- Stores: `apps/frontend/src/stores/` +- Inventario: `orchestration/inventarios/FRONTEND_INVENTORY.yml` + +## Triggers Activos + +- `@TRIGGER-MC-INVENTARIOS` - Actualizar inventario + +## Validaciones Pre-Commit + +```bash +# Build +cd apps/frontend && npm run build + +# Lint +npm run lint + +# TypeCheck +npm run typecheck +``` + +## Patrones Requeridos + +1. **Multi-tenancy:** Usar `useTenant()` para contexto +2. **Loading States:** Skeleton loaders para UX en tienda +3. **Error Handling:** Error boundaries por seccion +4. **Accessibility:** ARIA labels en componentes interactivos +5. **Responsive:** Mobile-first (uso en tablets en tienda) + +## Paginas POS Principales + +| Pagina | Descripcion | +|--------|-------------| +| /pos | Punto de venta principal | +| /products | Catalogo de productos | +| /inventory | Control de inventario | +| /customers | Gestion de clientes | +| /sales | Historial de ventas | +| /reports | Reportes y analytics | + +## Referencias + +- `@MC_INV_FE` - FRONTEND_INVENTORY.yml +- `@MC_QUICK_API` - QUICK-API.yml (endpoints disponibles) diff --git a/orchestration/agents/perfiles/PERFIL-MOBILE-AGENT.md b/orchestration/agents/perfiles/PERFIL-MOBILE-AGENT.md new file mode 100644 index 000000000..7d7c52ff9 --- /dev/null +++ b/orchestration/agents/perfiles/PERFIL-MOBILE-AGENT.md @@ -0,0 +1,117 @@ +# PERFIL: Mobile Agent + +**ID:** MC-MOBILE-AGENT +**Version:** 1.0.0 +**Proyecto:** michangarrito +**Hereda de:** @WS_PERFIL_FRONTEND + +--- + +## Identidad + +**Rol:** Mobile Developer especializado en React Native para POS +**Alcance:** Screens, components, navigation, native features + +## Responsabilidades + +### Primarias +- Implementar screens en React Native +- Crear componentes mobile optimizados +- Configurar navegacion +- Integrar con APIs del backend +- Implementar features nativas (camara, notificaciones) + +### Secundarias +- Coordinar con BACKEND-AGENT para APIs +- Mantener MOBILE_INVENTORY.yml actualizado +- Optimizar para dispositivos de gama baja + +## Herramientas + +### Stack Tecnologico +- **Framework:** React Native +- **Navigation:** React Navigation +- **Data Fetching:** TanStack Query +- **State:** Zustand +- **UI:** NativeWind (Tailwind for RN) +- **Forms:** React Hook Form + Zod + +### Estructura de Screen +``` +apps/mobile/src/screens/{feature}/ +├── index.tsx # Export principal +├── {Feature}Screen.tsx # Componente de screen +├── components/ # Componentes locales +│ └── {Component}.tsx +└── hooks/ # Hooks locales + └── use{Feature}.ts +``` + +### Patron de Hook Mobile +```typescript +export function useFeature() { + const { tenantId } = useTenant(); + + return useQuery({ + queryKey: ['feature', tenantId], + queryFn: () => featureApi.getAll(tenantId), + enabled: !!tenantId, + staleTime: 5 * 60 * 1000, // 5 min cache para mobile + }); +} +``` + +### Ubicaciones +- Screens: `apps/mobile/src/screens/` +- Components: `apps/mobile/src/components/` +- Hooks: `apps/mobile/src/hooks/` +- Navigation: `apps/mobile/src/navigation/` +- Inventario: `orchestration/inventarios/MOBILE_INVENTORY.yml` + +## Triggers Activos + +- `@TRIGGER-MC-INVENTARIOS` - Actualizar inventario + +## Validaciones Pre-Commit + +```bash +# TypeCheck +cd apps/mobile && npm run typecheck + +# Lint +npm run lint + +# Tests +npm run test +``` + +## Patrones Requeridos + +1. **Multi-tenancy:** Usar `useTenant()` para contexto +2. **Offline-First:** Cache agresivo para uso sin internet +3. **Performance:** Memoization y lazy loading +4. **Accessibility:** VoiceOver/TalkBack support +5. **Responsive:** Adaptacion a diferentes tamanios de pantalla + +## Screens POS Principales + +| Screen | Descripcion | +|--------|-------------| +| POSScreen | Punto de venta tactil | +| ProductsScreen | Catalogo de productos | +| InventoryScreen | Control de inventario | +| CustomersScreen | Gestion de clientes | +| SalesScreen | Historial de ventas | +| SettingsScreen | Configuracion | + +## Features Nativas + +- **Camara:** Escaneo de codigos de barras +- **Notificaciones:** Alertas de stock bajo +- **Bluetooth:** Impresora de tickets +- **NFC:** Pagos contactless (futuro) + +## Referencias + +- `@MC_INV_MOBILE` - MOBILE_INVENTORY.yml +- `@MC_QUICK_API` - QUICK-API.yml (endpoints disponibles) diff --git a/orchestration/agents/trazas/_INDEX.yml b/orchestration/agents/trazas/_INDEX.yml new file mode 100644 index 000000000..f81f07f15 --- /dev/null +++ b/orchestration/agents/trazas/_INDEX.yml @@ -0,0 +1,53 @@ +# =============================================================================== +# INDICE DE TRAZAS DE AGENTES - MICHANGARRITO +# =============================================================================== +# +# Proposito: Registro de actividad de agentes en el proyecto +# Alias: @MC_TRAZAS_INDEX +# +# =============================================================================== + +version: "1.0.0" +created: "2026-01-16" +updated: "2026-01-16" +proyecto: "michangarrito" + +# ------------------------------------------------------------------------------- +# AGENTES REGISTRADOS +# ------------------------------------------------------------------------------- + +agentes: + MC-DDL-AGENT: + perfil: "orchestration/agents/perfiles/PERFIL-DDL-AGENT.md" + trazas: [] + ultima_actividad: null + + MC-BACKEND-AGENT: + perfil: "orchestration/agents/perfiles/PERFIL-BACKEND-AGENT.md" + trazas: [] + ultima_actividad: null + + MC-FRONTEND-AGENT: + perfil: "orchestration/agents/perfiles/PERFIL-FRONTEND-AGENT.md" + trazas: [] + ultima_actividad: null + + MC-MOBILE-AGENT: + perfil: "orchestration/agents/perfiles/PERFIL-MOBILE-AGENT.md" + trazas: [] + ultima_actividad: null + +# ------------------------------------------------------------------------------- +# ESTADISTICAS +# ------------------------------------------------------------------------------- + +estadisticas: + total_agentes: 4 + total_trazas: 0 + ultima_traza: null + +# ------------------------------------------------------------------------------- +# FORMATO DE TRAZA +# ------------------------------------------------------------------------------- +# Las trazas se nombran: TRAZA-{AGENTE}-{YYYY-MM-DD}-{NNN}.md +# Ejemplo: TRAZA-MC-BACKEND-AGENT-2026-01-16-001.md diff --git a/orchestration/directivas/README.md b/orchestration/directivas/README.md new file mode 100644 index 000000000..028d142eb --- /dev/null +++ b/orchestration/directivas/README.md @@ -0,0 +1,53 @@ +# Directivas de MiChangarrito + +**Version:** 1.0.0 +**Actualizado:** 2026-01-16 + +--- + +## Proposito + +Este directorio contiene directivas especificas del proyecto michangarrito. +Las directivas generales se heredan del workspace padre (`/orchestration/directivas/`). + +## Estructura + +``` +directivas/ +├── README.md <- Este archivo +├── proyecto-triggers/ <- Triggers especificos del proyecto +│ ├── TRIGGER-COHERENCIA-CAPAS.md +│ └── TRIGGER-INVENTARIOS.md +└── proyecto-modos/ <- Modos especificos (si aplica) + └── README.md +``` + +## Herencia + +MiChangarrito hereda tipo INTEGRATES de template-saas: + +| Categoria | Heredado de | Ruta | +|-----------|-------------|------| +| Principios | Workspace | `/orchestration/directivas/principios/` | +| SIMCO | Workspace | `/orchestration/directivas/simco/` | +| Triggers | Workspace | `/orchestration/directivas/triggers/` | +| Modos | Workspace | `/orchestration/directivas/modos/` | + +## Triggers Especificos + +Los triggers en `proyecto-triggers/` son **adicionales** a los del workspace +y aplican especificamente a michangarrito. + +### TRIGGER-COHERENCIA-CAPAS.md + +Valida que cambios en DDL tengan entities correspondientes en backend. +Adaptado para arquitectura monorepo con apps/backend y apps/mobile. + +### TRIGGER-INVENTARIOS.md + +Valida que los inventarios esten sincronizados con el codigo. + +## Referencias + +- `@WS_DIRECTIVAS` - Directivas del workspace +- `@MC_DIRECTIVAS` - Este directorio diff --git a/orchestration/directivas/proyecto-triggers/TRIGGER-COHERENCIA-CAPAS.md b/orchestration/directivas/proyecto-triggers/TRIGGER-COHERENCIA-CAPAS.md new file mode 100644 index 000000000..56c3d1a51 --- /dev/null +++ b/orchestration/directivas/proyecto-triggers/TRIGGER-COHERENCIA-CAPAS.md @@ -0,0 +1,107 @@ +# TRIGGER: Coherencia Entre Capas + +**ID:** TRIGGER-MC-COHERENCIA +**Version:** 1.0.0 +**Prioridad:** P1 (Bloqueante) +**Activacion:** Automatica en cambios DDL/Backend +**Hereda de:** template-saas (INTEGRATES) + +--- + +## Proposito + +Garantizar coherencia entre las capas DDL, Backend y Frontend del proyecto MiChangarrito. +Cada tabla DDL debe tener su entity correspondiente en el backend. + +## Contexto del Proyecto + +MiChangarrito es una plataforma POS multi-tenant con: +- **Backend:** NestJS + TypeScript +- **Frontend:** React + Vite +- **Mobile:** React Native +- **Database:** PostgreSQL 16+ con RLS + +## Activacion + +Este trigger se activa cuando: +- Se crea/modifica archivo en `database/schemas/*/tables/*.sql` +- Se crea/modifica archivo en `apps/backend/src/modules/*/entities/*.entity.ts` +- Se ejecuta validacion manual con `@MC_VALIDATE_COHERENCIA` + +## Validaciones + +### 1. DDL -> Entity (Obligatorio) + +``` +Para cada tabla en DDL: + ├── Verificar que existe entity correspondiente + ├── Verificar que columnas coincidan (nombre, tipo) + ├── Verificar que relaciones esten mapeadas + └── Documentar excepciones justificadas +``` + +**Excepciones Permitidas:** +- Tablas M:N gestionadas por TypeORM (documentar en ENTITIES-CATALOG) +- Tablas de auditoria automatica (documentar en DATABASE-SCHEMA) +- Tablas de sistema/migracion + +### 2. Entity -> Service (Recomendado) + +``` +Para cada entity: + ├── Verificar que existe service que la usa + └── Verificar que operaciones CRUD estan implementadas (si aplica) +``` + +### 3. Service -> Controller (Si expone API) + +``` +Para cada service expuesto: + ├── Verificar que existe controller + ├── Verificar que endpoints estan documentados + └── Verificar que DTOs existen para request/response +``` + +## Ubicaciones Especificas + +| Capa | Ubicacion | +|------|-----------| +| DDL | `database/schemas/{schema}/tables/` | +| Entities | `apps/backend/src/modules/{mod}/entities/` | +| Services | `apps/backend/src/modules/{mod}/` | +| Controllers | `apps/backend/src/modules/{mod}/` | + +## Resultado de Validacion + +### Exito +```yaml +status: "pass" +ddl_tables: +entities: +coverage: 100% +exceptions: 0 +``` + +### Fallo (Bloqueante) +```yaml +status: "fail" +ddl_tables: +entities: +coverage: +missing: + - tabla: "new_table" + schema: "new_schema" + accion_requerida: "Crear entity o documentar excepcion" +``` + +## Acciones Correctivas + +1. **Si falta entity:** Crear entity en `apps/backend/src/modules/{modulo}/entities/` +2. **Si es excepcion:** Documentar en `docs/_definitions/ENTITIES-CATALOG.md` +3. **Si es tabla temporal:** Agregar a lista de exclusiones + +## Referencias + +- `@MC_DEF_ENTITIES` - Catalogo de entities +- `@MC_DEF_DB` - Schema de base de datos +- `@MC_INV_BE` - Inventario backend diff --git a/orchestration/directivas/proyecto-triggers/TRIGGER-INVENTARIOS.md b/orchestration/directivas/proyecto-triggers/TRIGGER-INVENTARIOS.md new file mode 100644 index 000000000..46f860aab --- /dev/null +++ b/orchestration/directivas/proyecto-triggers/TRIGGER-INVENTARIOS.md @@ -0,0 +1,141 @@ +# TRIGGER: Inventarios Sincronizados + +**ID:** TRIGGER-MC-INVENTARIOS +**Version:** 1.0.0 +**Prioridad:** P2 (Importante) +**Activacion:** Post-tarea con cambios de codigo +**Hereda de:** template-saas (INTEGRATES) + +--- + +## Proposito + +Mantener los inventarios del proyecto sincronizados con el codigo real. +Detectar discrepancias entre lo documentado y lo implementado. + +## Contexto del Proyecto + +MiChangarrito tiene estructura monorepo con: +- `apps/backend/` - API NestJS +- `apps/frontend/` - Web React +- `apps/mobile/` - React Native +- `apps/whatsapp-service/` - Integracion WhatsApp +- `apps/mcp-server/` - Servidor MCP para LLM + +## Activacion + +Este trigger se activa cuando: +- Se completa una tarea que modifica codigo +- Se ejecuta validacion manual con `@MC_VALIDATE_INVENTARIOS` +- Se prepara release + +## Inventarios a Validar + +| Inventario | Ubicacion | Valida | +|------------|-----------|--------| +| DATABASE_INVENTORY.yml | orchestration/inventarios/ | Schemas, tablas, enums, funciones | +| BACKEND_INVENTORY.yml | orchestration/inventarios/ | Modulos, services, entities, tests | +| FRONTEND_INVENTORY.yml | orchestration/inventarios/ | Pages, components, hooks | +| MOBILE_INVENTORY.yml | orchestration/inventarios/ | Screens, components, navigation | +| MASTER_INVENTORY.yml | orchestration/inventarios/ | Totales consolidados | + +## Validaciones + +### 1. DATABASE_INVENTORY.yml + +```bash +# Validar schemas +ls database/schemas/ | wc -l # Debe coincidir con total_schemas + +# Validar tablas +find database/schemas -name "*.sql" -path "*tables*" | wc -l +``` + +### 2. BACKEND_INVENTORY.yml + +```bash +# Validar entities +find apps/backend/src/modules -name "*.entity.ts" | wc -l + +# Validar services +find apps/backend/src/modules -name "*.service.ts" | wc -l + +# Validar controllers +find apps/backend/src/modules -name "*.controller.ts" | wc -l +``` + +### 3. FRONTEND_INVENTORY.yml + +```bash +# Validar pages +find apps/frontend/src/pages -name "*.tsx" | wc -l + +# Validar components +find apps/frontend/src/components -name "*.tsx" | wc -l +``` + +### 4. MOBILE_INVENTORY.yml + +```bash +# Validar screens +find apps/mobile/src/screens -name "*.tsx" | wc -l + +# Validar components +find apps/mobile/src/components -name "*.tsx" | wc -l +``` + +### 5. MASTER_INVENTORY.yml + +```yaml +# Totales deben coincidir con suma de inventarios individuales +backend_entities: sum(BACKEND_INVENTORY.entities) +frontend_pages: sum(FRONTEND_INVENTORY.pages) +mobile_screens: sum(MOBILE_INVENTORY.screens) +database_tables: sum(DATABASE_INVENTORY.tablas) +``` + +## Resultado de Validacion + +### Exito +```yaml +status: "pass" +inventarios: + database: "sync" + backend: "sync" + frontend: "sync" + mobile: "sync" + master: "sync" +discrepancias: 0 +``` + +### Advertencia +```yaml +status: "warning" +inventarios: + database: "sync" + backend: "desync" + frontend: "sync" + mobile: "sync" + master: "desync" +discrepancias: + - inventario: "BACKEND_INVENTORY.yml" + campo: "total_entities" + documentado: + real: + accion: "Actualizar inventario" +``` + +## Acciones Correctivas + +1. **Actualizar totales:** Corregir numeros en inventarios +2. **Agregar items faltantes:** Documentar nuevos artefactos +3. **Eliminar items obsoletos:** Remover referencias a codigo eliminado +4. **Actualizar MASTER:** Recalcular totales consolidados + +## Referencias + +- `@MC_INV_MASTER` - Inventario maestro +- `@MC_INV_DB` - Inventario database +- `@MC_INV_BE` - Inventario backend +- `@MC_INV_FE` - Inventario frontend +- `@MC_INV_MOBILE` - Inventario mobile