[MICHANGARRITO] feat: Add SaaS documentation structure from template-saas
- Add orchestration/directivas/ with proyecto-triggers - TRIGGER-COHERENCIA-CAPAS.md for DDL/Backend coherence - TRIGGER-INVENTARIOS.md for inventory synchronization - Add orchestration/agents/ with perfiles - PERFIL-DDL-AGENT.md - PERFIL-BACKEND-AGENT.md - PERFIL-FRONTEND-AGENT.md - PERFIL-MOBILE-AGENT.md (specific to mobile POS) - Add MAPA-DOCUMENTACION.yml as central reference Inheritance: INTEGRATES from template-saas Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
c73ac4deaa
commit
e046ba8143
165
orchestration/MAPA-DOCUMENTACION.yml
Normal file
165
orchestration/MAPA-DOCUMENTACION.yml
Normal file
@ -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"
|
||||
68
orchestration/agents/README.md
Normal file
68
orchestration/agents/README.md
Normal file
@ -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
|
||||
125
orchestration/agents/perfiles/PERFIL-BACKEND-AGENT.md
Normal file
125
orchestration/agents/perfiles/PERFIL-BACKEND-AGENT.md
Normal file
@ -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
|
||||
92
orchestration/agents/perfiles/PERFIL-DDL-AGENT.md
Normal file
92
orchestration/agents/perfiles/PERFIL-DDL-AGENT.md
Normal file
@ -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
|
||||
110
orchestration/agents/perfiles/PERFIL-FRONTEND-AGENT.md
Normal file
110
orchestration/agents/perfiles/PERFIL-FRONTEND-AGENT.md
Normal file
@ -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)
|
||||
117
orchestration/agents/perfiles/PERFIL-MOBILE-AGENT.md
Normal file
117
orchestration/agents/perfiles/PERFIL-MOBILE-AGENT.md
Normal file
@ -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)
|
||||
53
orchestration/agents/trazas/_INDEX.yml
Normal file
53
orchestration/agents/trazas/_INDEX.yml
Normal file
@ -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
|
||||
53
orchestration/directivas/README.md
Normal file
53
orchestration/directivas/README.md
Normal file
@ -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
|
||||
@ -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: <total>
|
||||
entities: <total>
|
||||
coverage: 100%
|
||||
exceptions: 0
|
||||
```
|
||||
|
||||
### Fallo (Bloqueante)
|
||||
```yaml
|
||||
status: "fail"
|
||||
ddl_tables: <total+1>
|
||||
entities: <total>
|
||||
coverage: <porcentaje>
|
||||
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
|
||||
@ -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: <doc>
|
||||
real: <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
|
||||
Loading…
Reference in New Issue
Block a user