platform-marketing-content/orchestration/directivas/GUIA-NOMENCLATURA-PMC.md

# Guia de Nomenclatura - Platform Marketing Content

**Version:** 1.0.0
**Fecha:** 2025-12-08
**Hereda de:** core/orchestration/directivas/ESTANDARES-NOMENCLATURA-BASE.md

---

## Proposito

Esta guia define las convenciones de nomenclatura especificas para el proyecto PMC, complementando los estandares base del workspace.

---

## 1. Identificadores de Modulos

### Formato
```
PMC-{NNN}-{NOMBRE}
```

### Modulos Definidos

| ID | Nombre | Descripcion |
|----|--------|-------------|
| PMC-001 | TENANTS | Multi-tenancy y planes |
| PMC-002 | CRM | Clientes, marcas, productos |
| PMC-003 | PROJECTS | Proyectos y campanas |
| PMC-004 | GENERATION | Motor de generacion IA |
| PMC-005 | AUTOMATION | Flujos automatizados |
| PMC-006 | ASSETS | DAM (Digital Asset Management) |
| PMC-007 | ADMIN | Usuarios, roles, configuracion |
| PMC-008 | ANALYTICS | Dashboards y reportes |

---

## 2. Base de Datos

### Schemas

```sql
-- Schemas del proyecto
auth           -- Autenticacion y sesiones
crm            -- Clientes, marcas, productos, oportunidades
projects       -- Proyectos, campanas, briefs
generation     -- Jobs, workflows, modelos
assets         -- Assets, colecciones, versiones
automation     -- Flujos, webhooks, eventos
analytics      -- Metricas, reportes
config         -- Settings, feature flags
```

### Tablas

```sql
-- Formato: {schema}.{entidad_plural}
crm.clients
crm.brands
crm.products
crm.contacts
crm.opportunities

projects.projects
projects.campaigns
projects.briefs
projects.campaign_assets

generation.jobs
generation.workflow_templates
generation.custom_models
generation.text_generations

assets.assets
assets.asset_versions
assets.collections
assets.collection_assets

-- Tablas de relacion: {entidad1}_{entidad2}
projects.campaign_assets
assets.collection_assets
```

### Columnas Comunes

```sql
-- Identificadores
id              UUID PRIMARY KEY DEFAULT gen_random_uuid()
tenant_id       UUID NOT NULL REFERENCES auth.tenants(id)

-- Timestamps
created_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW()
updated_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW()
deleted_at      TIMESTAMP WITH TIME ZONE  -- Soft delete

-- Auditoria
created_by      UUID REFERENCES auth.users(id)
updated_by      UUID REFERENCES auth.users(id)
```

### Foreign Keys

```sql
-- Formato: fk_{tabla}_{columna}
CONSTRAINT fk_clients_tenant FOREIGN KEY (tenant_id) REFERENCES auth.tenants(id)
CONSTRAINT fk_brands_client FOREIGN KEY (client_id) REFERENCES crm.clients(id)
```

### Indices

```sql
-- Formato: idx_{tabla}_{columnas}
CREATE INDEX idx_clients_tenant ON crm.clients(tenant_id);
CREATE INDEX idx_assets_tenant_status ON assets.assets(tenant_id, status);
CREATE UNIQUE INDEX idx_brands_tenant_slug ON crm.brands(tenant_id, slug);
```

### Politicas RLS

```sql
-- Formato: rls_{tabla}_{accion}
CREATE POLICY rls_clients_tenant_isolation ON crm.clients
    USING (tenant_id = current_setting('app.current_tenant')::uuid);
```

---

## 3. Backend (NestJS)

### Estructura de Modulos

```
src/modules/{nombre-modulo}/
├── {nombre-modulo}.module.ts
├── controllers/
│   └── {nombre}.controller.ts
├── services/
│   └── {nombre}.service.ts
├── entities/
│   └── {nombre}.entity.ts
├── dto/
│   ├── create-{nombre}.dto.ts
│   ├── update-{nombre}.dto.ts
│   └── {nombre}-response.dto.ts
├── guards/
│   └── {nombre}.guard.ts
├── decorators/
│   └── {nombre}.decorator.ts
└── __tests__/
    └── {nombre}.service.spec.ts
```

### Naming de Archivos

```typescript
// Entities (singular, PascalCase en clase)
client.entity.ts         → export class Client
brand.entity.ts          → export class Brand
generation-job.entity.ts → export class GenerationJob

// Services (singular)
client.service.ts        → export class ClientService
brand.service.ts         → export class BrandService

// Controllers (plural para REST)
clients.controller.ts    → export class ClientsController
brands.controller.ts     → export class BrandsController

// DTOs (accion-entidad)
create-client.dto.ts     → export class CreateClientDto
update-brand.dto.ts      → export class UpdateBrandDto
client-response.dto.ts   → export class ClientResponseDto
```

### Endpoints REST

```typescript
// Formato: /api/v1/{modulo}/{recurso}
// Usar kebab-case para rutas

// CRUD basico
GET    /api/v1/crm/clients           // Listar
GET    /api/v1/crm/clients/:id       // Obtener
POST   /api/v1/crm/clients           // Crear
PUT    /api/v1/crm/clients/:id       // Actualizar completo
PATCH  /api/v1/crm/clients/:id       // Actualizar parcial
DELETE /api/v1/crm/clients/:id       // Eliminar

// Recursos anidados
GET    /api/v1/crm/clients/:clientId/brands
POST   /api/v1/crm/clients/:clientId/brands

// Acciones especiales
POST   /api/v1/crm/clients/:id/activate
POST   /api/v1/generation/jobs/:id/cancel
GET    /api/v1/generation/jobs/:id/progress
```

---

## 4. Frontend (React)

### Estructura de Carpetas

```
src/
├── components/
│   ├── common/              # Componentes reutilizables
│   │   ├── Button/
│   │   ├── Modal/
│   │   └── Table/
│   └── {modulo}/            # Componentes por modulo
│       ├── ClientCard/
│       ├── BrandList/
│       └── CampaignForm/
├── pages/
│   ├── crm/
│   │   ├── ClientsPage.tsx
│   │   └── BrandsPage.tsx
│   └── generation/
│       └── GenerationPage.tsx
├── hooks/
│   ├── useClients.ts
│   └── useGeneration.ts
├── stores/
│   ├── useAuthStore.ts
│   └── useTenantStore.ts
├── services/
│   └── api/
│       ├── clients.api.ts
│       └── generation.api.ts
└── types/
    ├── client.types.ts
    └── generation.types.ts
```

### Naming de Componentes

```typescript
// Componentes (PascalCase)
ClientCard.tsx           → export const ClientCard
BrandList.tsx            → export const BrandList
CampaignForm.tsx         → export const CampaignForm

// Pages (PascalCase + Page suffix)
ClientsPage.tsx          → export const ClientsPage
GenerationPage.tsx       → export const GenerationPage

// Hooks (camelCase con use prefix)
useClients.ts            → export const useClients
useGeneration.ts         → export const useGeneration

// Stores (camelCase con use prefix + Store suffix)
useAuthStore.ts          → export const useAuthStore
useTenantStore.ts        → export const useTenantStore

// Types (PascalCase)
client.types.ts          → export interface Client
generation.types.ts      → export interface GenerationJob
```

---

## 5. Documentacion

### Archivos de Modulos

```
PMC-{NNN}-{NOMBRE}.md           # Definicion de modulo
RF-PMC-{NNN}-{NOMBRE}.md        # Requerimientos funcionales
EPIC-{NNN}-{NOMBRE}.md          # Epica con user stories
```

### Reportes y Trazas

```
REPORTE-{DESCRIPCION}-YYYY-MM-DD.md    # Reportes con fecha
TRAZA-TAREAS-{CAPA}.md                 # Trazas por capa (BACKEND, FRONTEND, DATABASE)
ANALISIS-{TEMA}.md                      # Documentos de analisis
```

### IDs de Tareas

```
DB-{NNN}    # Tareas de base de datos
BE-{NNN}    # Tareas de backend
FE-{NNN}    # Tareas de frontend
REQ-{NNN}   # Tareas de requerimientos
```

---

## 6. Generacion de Contenido

### Workflows

```yaml
# Nombres de workflows (snake_case)
product_photo_synthetic
social_media_post
ad_variations_banner
virtual_avatar_consistent
brand_style_transfer
```

### Modelos Personalizados

```yaml
# Nombres de modelos (kebab-case)
lora-{tenant_slug}-{brand_slug}-v{N}
checkpoint-{tenant_slug}-{purpose}
embedding-{tenant_slug}-{concept}

# Ejemplos
lora-acme-corp-main-brand-v1
lora-acme-corp-product-shoes-v2
checkpoint-acme-corp-realistic
```

### Jobs de Generacion

```yaml
# Estados de jobs
queued       # En cola
processing   # Procesando
completed    # Completado
failed       # Fallido
cancelled    # Cancelado
```

---

## 7. Automation (n8n)

### Nombres de Flujos

```yaml
# Formato: {trigger}_{action}_{target}
product_created_generate_kit
campaign_approved_notify_client
job_completed_update_assets
quota_exceeded_notify_admin
```

### Webhooks

```yaml
# Formato: /webhooks/{source}/{event}
/webhooks/crm/product-created
/webhooks/generation/job-completed
/webhooks/n8n/flow-callback
```

---

## 8. Assets y Storage

### Estructura S3/MinIO

```
{bucket}/
├── {tenant_slug}/
│   ├── assets/
│   │   ├── originals/
│   │   ├── thumbnails/
│   │   └── processed/
│   ├── generated/
│   │   ├── images/
│   │   └── videos/
│   ├── models/
│   │   ├── loras/
│   │   └── checkpoints/
│   └── temp/
```

### Nombres de Archivos

```yaml
# Assets subidos
{uuid}.{extension}
{uuid}_thumb.{extension}

# Assets generados
gen_{job_id}_{index}.{extension}
gen_{job_id}_{index}_thumb.{extension}

# Modelos
lora_{tenant}_{brand}_{version}.safetensors
```

---

## Referencias

- Estandares base: `core/orchestration/directivas/simco/SIMCO-CREAR.md` (seccion nomenclatura)
- Nomenclatura legacy: `core/orchestration/directivas/legacy/ESTANDARES-NOMENCLATURA-BASE.md`

---

**Generado por:** Requirements-Analyst
**Fecha:** 2025-12-08