erp-construccion/orchestration/NAMING-CONVENTIONS.md

NAMING CONVENTIONS - ERP CONSTRUCCION

Convenciones de Nomenclatura Unificadas

Version: 1.0.0 Fecha: 2025-12-06 Estado: ACTIVO

---

1. SCHEMAS DE BASE DE DATOS

1.1 Nomenclatura Oficial

Schema	Proposito	Tipo	Archivo DDL
construction	Proyectos, estructura de obra, avances, calidad, contratos	Especifico	construction-schema-ddl.sql
estimates	Presupuestos, estimaciones, generadores, anticipos	Especifico	estimates-schema-ddl.sql
infonavit	Integracion INFONAVIT, RUV, derechohabientes	Especifico	infonavit-schema-ddl.sql
hr	Extension RRHH: asistencias, destajo, cuadrillas	Extension	hr-ext-schema-ddl.sql
inventory	Extension Inventario: almacenes obra, requisiciones, consumos	Extension	inventory-ext-schema-ddl.sql
purchase	Extension Compras: OC construccion, comparativos	Extension	purchase-ext-schema-ddl.sql

1.2 Mapeo de Nombres Anteriores (DEPRECADOS)

Nombre Anterior	Nombre Actual	Accion
project_management	construction	MIGRAR
financial_management	estimates	MIGRAR
hr_management	hr	MIGRAR
purchasing_management	purchase	MIGRAR
quality_management	construction (integrado)	ELIMINAR
contract_management	construction (integrado)	ELIMINAR
crm_management	infonavit (integrado)	ELIMINAR
assets_management	(Fase 2 - pendiente)	POSTERGAR
documents_management	(Fase 2 - pendiente)	POSTERGAR

1.3 Justificacion de Consolidacion

Antes (11 schemas):

project_management, financial_management, hr_management,
purchasing_management, construction_management, quality_management,
infonavit_management, crm_management, contract_management,
assets_management, documents_management

Despues (6 schemas):

construction, estimates, infonavit, hr, inventory, purchase

Beneficios:

• Menos complejidad en queries cross-schema
• Alineacion con archivos DDL existentes
• Nombres cortos y claros
• Patron de extension consistente (_ext suffix)

---

2. CONVENCIONES DE TABLAS

2.1 Prefijos por Tipo

Tipo	Prefijo	Ejemplo
Tabla master	(ninguno)	fraccionamientos, estimaciones
Tabla detalle	(ninguno, singular)	estimacion_conceptos
Tabla extension	(schema).table_ext	hr.employee_construction
Tabla pivot/relacion	(entidad1)_(entidad2)	cuadrilla_miembros
Tabla historico	(tabla)_history	estimaciones_history

2.2 Nombres en Espanol vs Ingles

Regla General: Usar espanol para entidades de dominio mexicano, ingles para terminos tecnicos.

Tipo	Idioma	Ejemplos
Entidades de dominio MX	Espanol	fraccionamientos, lotes, estimaciones, derechohabientes
Terminos INFONAVIT	Espanol	cofinavit, ruv, puntos_ecologicos
Campos tecnicos	Ingles	tenant_id, created_at, is_active
Campos de auditoria	Ingles	created_by, updated_at, deleted_at
Estados/Enums	Ingles	draft, approved, cancelled

2.3 Sufijos Estandar

Sufijo	Significado	Ejemplo
_id	Foreign key	fraccionamiento_id
_at	Timestamp	created_at, approved_at
_by	Usuario que ejecuto	created_by, approved_by
_date	Solo fecha	requisition_date
_number	Codigo/numero	requisition_number
_amount	Monto monetario	total_amount
_quantity	Cantidad	quantity_requested

---

3. CONVENCIONES DE MODULOS

3.1 Codigos de Modulo

Prefijo	Significado	Rango
MAI-	Modulo Alcance Inicial (Fase 1)	001-019
MAE-	Modulo Alcance Enterprise (Fase 2)	014-016
MAA-	Modulo Alcance Avanzado (Fase 3)	017+
MOB-	Aplicacion Movil	001-005

3.2 Mapeo Modulo -> Schema

Modulo	Schema Principal	Schemas Secundarios
MAI-001	auth (core)	-
MAI-002	construction	-
MAI-003	estimates	construction
MAI-004	purchase, inventory	construction
MAI-005	construction	estimates
MAI-006	(reportes - sin schema)	todos
MAI-007	hr	construction
MAI-008	estimates	construction
MAI-009	construction	-
MAI-010	infonavit	-
MAI-011	infonavit	-
MAI-012	construction	-
MAI-013	(admin - usa core)	estimates
MAI-018	construction	estimates

---

4. CONVENCIONES DE CODIGO

4.1 Backend (Node.js/TypeScript)

// Entidades - PascalCase singular
class Fraccionamiento { }
class Estimacion { }
class DerechoHabiente { }

// Services - PascalCase + Service
class FraccionamientoService { }
class EstimacionService { }

// Controllers - PascalCase + Controller
class FraccionamientoController { }

// Repositories - PascalCase + Repository
class FraccionamientoRepository { }

// DTOs - PascalCase + sufijo
class CreateFraccionamientoDto { }
class UpdateFraccionamientoDto { }
class FraccionamientoResponseDto { }

// Archivos - kebab-case
fraccionamiento.entity.ts
fraccionamiento.service.ts
fraccionamiento.controller.ts
create-fraccionamiento.dto.ts

4.2 Frontend (React/TypeScript)

// Componentes - PascalCase
FraccionamientoList.tsx
FraccionamientoForm.tsx
FraccionamientoCard.tsx

// Hooks - camelCase con prefijo use
useFraccionamientos.ts
useEstimacion.ts

// Stores (Zustand) - camelCase + Store
fraccionamientoStore.ts
estimacionStore.ts

// Pages - PascalCase + Page
FraccionamientosPage.tsx
EstimacionDetailPage.tsx

// Archivos - kebab-case o PascalCase (consistente por proyecto)

4.3 API Endpoints

# Patron RESTful
GET    /api/v1/construccion/fraccionamientos
GET    /api/v1/construccion/fraccionamientos/:id
POST   /api/v1/construccion/fraccionamientos
PUT    /api/v1/construccion/fraccionamientos/:id
DELETE /api/v1/construccion/fraccionamientos/:id

# Recursos anidados
GET    /api/v1/construccion/fraccionamientos/:id/etapas
GET    /api/v1/construccion/fraccionamientos/:id/lotes

# Acciones especiales (verbos)
POST   /api/v1/estimaciones/:id/aprobar
POST   /api/v1/estimaciones/:id/facturar

---

5. CONVENCIONES DE DOCUMENTACION

5.1 Archivos de Especificacion

Tipo	Prefijo	Ejemplo
Requerimiento Funcional	RF-	RF-MAI002-001.md
Especificacion Tecnica	ET-	ET-MAI002-DB-001.md
User Story	US-	US-MAI002-001.md
ADR	ADR-	ADR-001-arquitectura-multi-tenant.md

5.2 Nomenclatura ET

ET-{MODULO}-{CAPA}-{NUMERO}.md

Capas:
- DB  = Database
- BE  = Backend
- FE  = Frontend
- API = API/Integracion
- MOB = Mobile

---

6. ACTUALIZACIONES REQUERIDAS

6.1 Inventarios a Actualizar

• MASTER_INVENTORY.yml - Cambiar nombres de schemas
• DATABASE_INVENTORY.yml - Alinear con DDL real
• DEPENDENCY_GRAPH.yml - Verificar referencias

6.2 Documentacion a Actualizar

• Especificaciones ET--DB- que referencian schemas antiguos
• MATRIZ-TRAZABILIDAD-COMPLETA.md

---

7. VALIDACION

7.1 Script de Validacion

#!/bin/bash
# validate-naming.sh

# Verificar que schemas en DDL coinciden con NAMING-CONVENTIONS
grep -r "CREATE SCHEMA" docs/04-modelado/database-design/schemas/*.sql

# Verificar referencias a schemas deprecados
grep -rn "project_management\|financial_management\|hr_management" .

7.2 Checklist de Cumplimiento

• Todos los DDL usan schemas oficiales
• MASTER_INVENTORY alineado
• DATABASE_INVENTORY alineado
• No hay referencias a schemas deprecados
• Entidades backend siguen convencion
• Componentes frontend siguen convencion

---

Fin del Documento

Autor: Requirements-Analyst Version: 1.0.0