9.2 KiB
9.2 KiB
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
-- 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
-- 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
-- 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
-- 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
-- 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
-- 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
// 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
// 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
// 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
# Nombres de workflows (snake_case)
product_photo_synthetic
social_media_post
ad_variations_banner
virtual_avatar_consistent
brand_style_transfer
Modelos Personalizados
# 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
# Estados de jobs
queued # En cola
processing # Procesando
completed # Completado
failed # Fallido
cancelled # Cancelado
7. Automation (n8n)
Nombres de Flujos
# Formato: {trigger}_{action}_{target}
product_created_generate_kit
campaign_approved_notify_client
job_completed_update_assets
quota_exceeded_notify_admin
Webhooks
# 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
# 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