# 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)

```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)

```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

```bash
#!/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*