workspace-v1/projects/erp-suite/docs/ESTANDAR-NOMENCLATURA-SCHEMAS.md

Estandar de Nomenclatura de Schemas - ERP Suite

Version: 1.0.0 Fecha: 2025-12-08 Autor: Architecture Analyst Agent Estado: APROBADO

---

1. Proposito

Este documento define la convencion de nomenclatura para schemas de base de datos en todo el ecosistema ERP-Suite, asegurando consistencia entre erp-core y todas las verticales.

---

2. Convencion General

2.1 Formato de Nombres

{prefijo}_{dominio}

Componente	Descripcion	Ejemplo
prefijo	Identificador del proyecto (3 letras)	erp, con, mec
dominio	Area funcional	auth, inventory, sales

2.2 Prefijos por Proyecto

Proyecto	Prefijo	Descripcion
erp-core	erp_	Schemas del core compartido
construccion	con_	Vertical de construccion
mecanicas-diesel	mec_	Vertical de mecanicas
clinicas	cli_	Vertical de clinicas
retail	ret_	Vertical de retail/POS
vidrio-templado	vit_	Vertical de vidrio templado

---

3. Schemas del ERP-Core

3.1 Schemas Base (Compartidos)

Schema Actual	Schema Estandar	Descripcion
auth	erp_auth	Autenticacion, sesiones
core	erp_core	Catalogos base, configuracion
financial	erp_financial	Contabilidad, diarios
inventory	erp_inventory	Productos, almacenes
purchase	erp_purchase	Ordenes de compra
sales	erp_sales	Cotizaciones, pedidos
projects	erp_projects	Proyectos, tareas
system	erp_system	Notificaciones, logs
billing	erp_billing	SaaS subscripciones
crm	erp_crm	Leads, oportunidades
hr	erp_hr	Recursos humanos
analytics	erp_analytics	Contabilidad analitica

---

4. Schemas por Vertical

4.1 Construccion (con_*)

Schema	Descripcion	Tablas Estimadas
con_projects	Proyectos, fraccionamientos, fases	8
con_budgets	Presupuestos, partidas, costos	10
con_estimates	Estimaciones, avances	6
con_infonavit	Integracion INFONAVIT	6
con_quality	Calidad, inspecciones	5
con_contracts	Contratos, subcontratos	5
con_hse	Seguridad, higiene	8

4.2 Mecanicas Diesel (mec_*)

Schema	Descripcion	Tablas
mec_workshop	Configuracion de taller	9
mec_service	Ordenes de servicio, diagnosticos	14
mec_parts	Refacciones, inventario	12
mec_vehicles	Vehiculos, flotas	8

4.3 Clinicas (cli_*)

Schema	Descripcion	Tablas Estimadas
cli_patients	Pacientes, expedientes	8
cli_appointments	Citas, agenda	5
cli_medical	Consultas, recetas	10
cli_lab	Laboratorio, resultados	6
cli_pharmacy	Farmacia, medicamentos	5
cli_imaging	Imagenologia, DICOM	4

4.4 Retail (ret_*)

Schema	Descripcion	Tablas Estimadas
ret_pos	Punto de venta, cajas	8
ret_store	Tiendas, sucursales	5
ret_loyalty	Fidelizacion, puntos	6
ret_ecommerce	Tienda online	8

4.5 Vidrio Templado (vit_*)

Schema	Descripcion	Tablas Estimadas
vit_production	Produccion, ordenes	8
vit_cutting	Corte, nesting	5
vit_tempering	Templado, hornos	5
vit_quality	Calidad, fragmentacion	6
vit_dispatch	Despacho, entregas	4

---

5. Convencion de Tablas

5.1 Formato de Nombres

-- Tablas en plural, snake_case
{schema}.{nombre_tabla_plural}

-- Ejemplos
erp_auth.users
erp_inventory.products
con_projects.developments
mec_service.work_orders

5.2 Columnas Obligatorias

Todas las tablas transaccionales DEBEN incluir:

-- Identificador
id UUID PRIMARY KEY DEFAULT gen_random_uuid()

-- Multi-tenancy
tenant_id UUID NOT NULL

-- Auditoria
created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
created_by UUID
updated_at TIMESTAMPTZ
updated_by UUID

-- Soft delete
is_active BOOLEAN DEFAULT true
deleted_at TIMESTAMPTZ
deleted_by UUID

5.3 Indices

-- Formato: idx_{tabla}_{columnas}
CREATE INDEX idx_users_tenant_id ON erp_auth.users(tenant_id);
CREATE INDEX idx_users_email ON erp_auth.users(email);

-- Unique con soft delete
CREATE UNIQUE INDEX idx_users_email_active
  ON erp_auth.users(email)
  WHERE deleted_at IS NULL;

5.4 Foreign Keys

-- Formato: fk_{origen}_to_{destino}
ALTER TABLE mec_service.work_orders
  ADD CONSTRAINT fk_work_orders_to_vehicles
  FOREIGN KEY (vehicle_id) REFERENCES mec_vehicles.vehicles(id);

5.5 Triggers

-- Formato: trg_{tabla}_{accion}
CREATE TRIGGER trg_users_updated_at
  BEFORE UPDATE ON erp_auth.users
  FOR EACH ROW EXECUTE FUNCTION update_updated_at();

---

6. RLS (Row-Level Security)

6.1 Patron Estandar

-- Habilitar RLS
ALTER TABLE {schema}.{tabla} ENABLE ROW LEVEL SECURITY;

-- Policy de aislamiento por tenant
CREATE POLICY tenant_isolation ON {schema}.{tabla}
  USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

6.2 Variable de Contexto por Vertical

Vertical	Variable de Contexto
erp-core	app.current_tenant_id
construccion	app.current_tenant_id
mecanicas	app.current_taller_id
clinicas	app.current_clinica_id
retail	app.current_tienda_id
vidrio	app.current_planta_id

---

7. Migracion de Schemas Existentes

7.1 Plan de Migracion

Para proyectos con schemas existentes, seguir este proceso:

1. Crear nuevo schema con prefijo correcto
2. Copiar estructura de tablas
3. Migrar datos con INSERT...SELECT
4. Actualizar referencias en codigo
5. Deprecar schema antiguo
6. Eliminar schema antiguo (siguiente version)

7.2 Mapeo de Schemas Existentes

erp-core (ya implementado)

-- Actual → Estandar (pendiente migracion)
auth → erp_auth
core → erp_core
financial → erp_financial
inventory → erp_inventory
purchase → erp_purchase
sales → erp_sales
projects → erp_projects
system → erp_system
billing → erp_billing
crm → erp_crm
hr → erp_hr
analytics → erp_analytics

construccion

-- Actual → Estandar
construction → con_projects
hr → con_hr (o mover a erp_hr)
hse → con_hse

mecanicas-diesel

-- Actual → Estandar
workshop_core → mec_workshop
service_management → mec_service
parts_management → mec_parts
vehicle_management → mec_vehicles

---

8. Validacion

8.1 Checklist de Validacion

validacion_schema:
  - [ ] Prefijo correcto segun proyecto
  - [ ] Nombre en snake_case
  - [ ] Tablas en plural
  - [ ] Columnas obligatorias presentes
  - [ ] RLS habilitado
  - [ ] Indices de tenant_id
  - [ ] Triggers de auditoria

8.2 Script de Validacion

-- Verificar schemas con prefijo correcto
SELECT schema_name
FROM information_schema.schemata
WHERE schema_name LIKE 'erp_%'
   OR schema_name LIKE 'con_%'
   OR schema_name LIKE 'mec_%'
   OR schema_name LIKE 'cli_%'
   OR schema_name LIKE 'ret_%'
   OR schema_name LIKE 'vit_%';

-- Verificar RLS habilitado
SELECT schemaname, tablename, rowsecurity
FROM pg_tables
WHERE schemaname LIKE '%_%'
  AND rowsecurity = false;

---

9. Excepciones

9.1 Schemas de Sistema

Los siguientes schemas NO requieren prefijo:

• public - Extensiones PostgreSQL
• pg_catalog - Sistema PostgreSQL
• information_schema - Metadatos

9.2 Schemas de Migracion

Durante la migracion, pueden coexistir schemas antiguos y nuevos:

-- Temporal durante migracion
auth           -- Antiguo (deprecado)
erp_auth       -- Nuevo (activo)

---

10. Referencias

Documento	Ubicacion
ADR-007 Database Design	erp-core/docs/97-adr/ADR-007-database-design.md
DDL erp-core	erp-core/database/ddl/
DDL mecanicas	mecanicas-diesel/database/ddl/
DDL construccion	construccion/database/ddl/

---

11. Historial de Cambios

Version	Fecha	Cambios
1.0.0	2025-12-08	Version inicial

---

Documento de arquitectura - ERP Suite Sistema NEXUS - Fabrica de Software con Agentes IA