# CLAUDE.md - ERP Transportistas

**Hereda de:** workspace-v2/CLAUDE.md + erp-core/CLAUDE.md
**Sistema:** SIMCO v4.0.0 + NEXUS v4.0
**Proyecto:** erp-transportistas
**Tipo:** CONSUMER (Vertical ERP)
**Version:** 1.0.0
**Actualizado:** 2026-01-25

---

## DESCRIPCION DEL PROYECTO

ERP especializado para empresas de transporte de carga, logistica y 3PL. Implementa funcionalidades especificas del sector:

- **Gestion de Flota:** Unidades tractoras, remolques, cajas, disponibilidad, documentacion
- **Ordenes de Transporte (OT):** Solicitudes de clientes con restricciones logisticas
- **Planeacion TMS:** Consolidacion, capacidad, asignacion de recursos
- **Despacho:** Checklists pre-viaje, sellos, evidencias de carga, liberacion
- **Tracking en Tiempo Real:** GPS/Telematica, eventos, alertas, ETA dinamico
- **POD (Proof of Delivery):** Evidencia de entrega, firma digital, fotos
- **Facturacion Transporte:** Tarifas por lane, recargos (fuel surcharge, detention)
- **CFDI Carta Porte:** Complemento 3.1 obligatorio para transporte
- **Control de Combustible:** Vales, tarjetas, consumo esperado vs real
- **Mantenimiento de Flota:** Preventivo por km/horas, correctivo, disponibilidad
- **Gestion de Carriers (Terceros):** Subcontratacion, documentos, scorecard

---

## EXTENSIONES LOCALES

Este archivo EXTIENDE (no reemplaza) las reglas de:
1. `../../CLAUDE.md` (workspace-v2)
2. `../erp-core/CLAUDE.md` (ERP base)

---

## STACK TECNOLOGICO

| Capa | Tecnologia | Version |
|------|------------|---------|
| Backend | NestJS | 10.x |
| Frontend | React | 18.x |
| Base de Datos | PostgreSQL + PostGIS | 15+ |
| ORM | TypeORM | 0.3.x |
| Cache | Redis (ioredis) | 7.x |
| Language | TypeScript | 5.x |
| Mobile | React Native/Expo | - |

---

## CREDENCIALES BD

```
Database: erp_transportistas_db
User: erp_admin
Password: erp_dev_2026
Port: 5432
Host: localhost
```

---

## ESTRUCTURA DEL PROYECTO

```
erp-transportistas/
├── CLAUDE.md               <- ESTE ARCHIVO
├── PROJECT-STATUS.md       <- Estado actual
├── INVENTARIO.yml          <- Inventario SIMCO
├── backend/                <- Backend NestJS
│   └── src/modules/        <- Modulos implementados
├── frontend/               <- Frontend React
├── database/
│   └── ddl/                <- DDL PostgreSQL
├── docs/                   <- Documentacion funcional
│   ├── 00-vision-general/
│   └── 02-definicion-modulos/
├── orchestration/          <- Sistema SIMCO local
└── .claude/                <- Instrucciones Claude Code
```

---

## SCHEMAS DE BASE DE DATOS

| Schema | Tablas | ENUMs | Archivo DDL | Descripcion |
|--------|--------|-------|-------------|-------------|
| transport | ~25 | ~10 | 01-transport-schema-ddl.sql | OT, Embarques, Viajes, Rutas |
| fleet | ~15 | ~8 | 02-fleet-schema-ddl.sql | Unidades, Remolques, Operadores |
| tracking | ~10 | ~5 | 03-tracking-schema-ddl.sql | Eventos, GPS, Alertas |
| fuel | ~8 | ~4 | 04-fuel-schema-ddl.sql | Combustible, Peajes, Gastos |
| maintenance | ~12 | ~6 | 05-maintenance-schema-ddl.sql | Mantenimiento, Ordenes de trabajo |
| carriers | ~8 | ~4 | 06-carriers-schema-ddl.sql | Terceros, Documentos, Scorecard |
| billing | ~10 | ~5 | 07-billing-transport-ddl.sql | Tarifas, Facturacion, Recargos |
| compliance | ~10 | ~5 | 08-compliance-schema-ddl.sql | Carta Porte, HOS, Inspecciones |
| **Total** | **~98** | **~47** | | |

---

## PUERTOS DE DESARROLLO

| Servicio | Puerto |
|----------|--------|
| Backend API | 3014 |
| Frontend Dev | 5174 |
| PostgreSQL | 5432 |
| Redis | 6379 |
| Adminer | 8080 |
| Mailhog | 8025 |

---

## MODULOS DEL SISTEMA

### Modulos Heredados de erp-core (22)

| Fase | Modulos | Herencia |
|------|---------|----------|
| Foundation | auth, users, roles, tenants | 100% |
| Core Business | catalogs, settings, financial, inventory, purchasing, sales | Extendido |
| Extended | audit, notifications, reports, crm, projects | Parcial |
| SaaS Platform | billing, plans, webhooks, feature_flags | 100% |
| IA/Intelligence | ai_integration, whatsapp_business, mcp_server | 100% |

### Modulos Propios - Fase 1 MAI (15)

| Codigo | Nombre | DDL | Backend | Descripcion |
|--------|--------|:---:|:-------:|-------------|
| MAI-001 | Fundamentos | - | - | Auth, RBAC, multi-tenancy (heredado) |
| MAI-002 | Clientes y Tarifas | - | - | Shippers, tarifas por lane, SLAs |
| MAI-003 | Ordenes de Transporte | - | - | OT, restricciones, multi-paradas |
| MAI-004 | Planeacion TMS | - | - | Consolidacion, capacidad, asignacion |
| MAI-005 | Despacho | - | - | Checklists, sellos, evidencias, salida |
| MAI-006 | Tracking | - | - | GPS, eventos, alertas, ETA |
| MAI-007 | POD y Cierre | - | - | Proof of Delivery, tiempos reales |
| MAI-008 | Incidencias | - | - | Reclamaciones, flujo, impacto |
| MAI-009 | Facturacion Transporte | - | - | Tarifas, recargos, conciliacion |
| MAI-010 | Liquidaciones | - | - | Pago operadores, viaticos, deducciones |
| MAI-011 | Gestion de Flota | - | - | Unidades, remolques, operadores |
| MAI-012 | Combustible y Gastos | - | - | Vales, peajes, control antifraude |
| MAI-013 | Mantenimiento Flota | - | - | Preventivo, correctivo, disponibilidad |
| MAI-014 | Carriers (Terceros) | - | - | Subcontratacion, documentos, scorecard |
| MAI-015 | Portal Cliente | - | - | Tracking, documentos, autoservicio |

### Modulos Propios - Fase 2 MAE (3)

| Codigo | Nombre | DDL | Backend | Descripcion |
|--------|--------|:---:|:-------:|-------------|
| MAE-016 | Carta Porte CFDI | - | - | Complemento 3.1, PAC, expediente |
| MAE-017 | HOS y Bitacora | - | - | Horas de servicio, NOM-087 |
| MAE-018 | Reportes y KPIs | - | - | OTIF, costo/km, disponibilidad |

### Modulos Propios - Fase 3 MAA (2)

| Codigo | Nombre | DDL | Backend | Descripcion |
|--------|--------|:---:|:-------:|-------------|
| MAA-019 | Optimizacion Rutas | - | - | Optimizacion, prediccion ETA |
| MAA-020 | Integraciones EDI | - | - | API clientes, intercambio datos |

---

## HERENCIA

### Este proyecto hereda de:
- `workspace-v2/orchestration/` - Directivas globales SIMCO
- `erp-core/` - Modulos base ERP, auth, multi-tenancy

### Extension de modulos erp-core:
- **tenants** → Empresas transportistas
- **catalogs** → Catalogos transporte (rutas, zonas, equipos)
- **financial** → Contabilidad transporte (CxC, CxP)
- **inventory** → Inventario de refacciones (minimo)
- **purchasing** → Compras de servicios
- **sales** → Servicios de transporte
- **crm** → CRM clientes/shippers
- **partners** → Clientes, proveedores, carriers
- **reports** → Reportes transporte
- **mcp_server** → Tools especificos transporte

---

## REGLAS ESPECIFICAS TRANSPORTE

### Nomenclatura de Codigo
```
Prefijo MAI-XXX: Modulo Aplicacion Inicial (Fase 1)
Prefijo MAE-XXX: Modulo Aplicacion Extendido (Fase 2)
Prefijo MAA-XXX: Modulo Aplicacion Avanzado (Fase 3)
```

### Entidades Criticas
- `OrdenTransporte` - Solicitud de servicio
- `Embarque` - Agrupacion de OTs
- `Viaje` - Ejecucion operativa
- `Unidad` - Tractora/remolque/caja
- `Operador` - Conductor con licencias
- `EventoTracking` - Posicion y eventos

### Workflow Viaje
```
BORRADOR → PLANEADO → DESPACHADO → EN_TRANSITO → EN_DESTINO → ENTREGADO (POD) → CERRADO → FACTURADO → COBRADO
```

### Carta Porte Obligatoria
- Version: 3.1 (vigente desde 17-jul-2024)
- Escenarios: CFDI Ingreso (servicio) / CFDI Traslado
- Validar datos minimos antes de liberar viaje
- Disponibilidad offline de PDF/XML/QR en app movil

---

## VALIDACIONES ADICIONALES

Ademas de las validaciones de erp-core:

1. **OT:** Validar ubicaciones con geocodificacion
2. **Viaje:** No liberar sin checklist completado
3. **POD:** Obligatorio para cerrar viaje
4. **Carta Porte:** Datos completos antes de timbrar
5. **Combustible:** Alertas por consumo anomalo
6. **Operador:** Bloquear si documentos vencidos
7. **Unidad:** Bloquear si mantenimiento vencido

---

## ALIASES LOCALES

- `@BACKEND` → backend/src/
- `@FRONTEND` → frontend/src/
- `@DDL` → database/ddl/
- `@DOCS` → docs/
- `@MODULOS` → docs/02-definicion-modulos/
- `@ORCHESTRATION` → orchestration/
- `@CONSTANTS` → .claude/constants/CONSTANTS-PROJECT.yml
- `@REQS` → docs/03-requerimientos/REQ-GIRO-TRANSPORTISTA.md

---

## ANTES DE IMPLEMENTAR

1. Verificar si es funcionalidad generica (va en erp-core)
2. Verificar si ya existe en modulos heredados
3. Revisar requerimientos en `docs/03-requerimientos/REQ-GIRO-TRANSPORTISTA.md`
4. Consultar documentacion funcional en `docs/02-definicion-modulos/`

---

## DESPUES DE IMPLEMENTAR

1. Actualizar PROJECT-STATUS.md
2. Actualizar INVENTARIO.yml si aplica
3. Documentar en carpeta del modulo correspondiente
4. Commit y push siguiendo SIMCO-GIT
5. Si afecta erp-core → evaluar propagacion inversa

---

## ESTADO ACTUAL

| Metrica | Valor |
|---------|-------|
| Progreso General | 0% (nuevo proyecto) |
| DDL Implementado | 0% |
| Backend Implementado | 0% |
| Frontend Implementado | 0% |
| Documentacion Funcional | 100% (requerimientos definidos) |
| Documentacion Tecnica | 20% |

---

## PROXIMOS PASOS

1. Crear repositorios Git (padre + submodulos)
2. Crear DDL de schemas principales
3. Implementar entities base de transporte
4. Implementar modulo MAI-003 (Ordenes de Transporte)
5. Implementar modulo MAI-006 (Tracking)
6. Implementar modulo MAE-016 (Carta Porte)

---

*ERP Transportistas v1.0.0 - Sistema SIMCO v4.0.0*