rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
4f8bccfbc3
erp-transportistas-v2/CLAUDE.md
Adrian Flores Cortes 37ed0aa919 feat: Initial project structure for ERP Transportistas 
Vertical ERP for freight transport and logistics companies.

Includes:
- Project configuration (CLAUDE.md, SIMCO orchestration)
- Backend submodule (NestJS 10.x)
- Frontend submodule (React 18.x + Vite)
- Database submodule (PostgreSQL 15 + PostGIS)
- Requirements documentation (REQ-GIRO-TRANSPORTISTA.md)
- 20 modules defined (MAI/MAE/MAA phases)

Key features:
- Transport orders (OT) management
- Fleet and driver management
- Real-time GPS tracking
- POD (Proof of Delivery)
- CFDI with Carta Porte 3.1 compliance
- Fuel and maintenance control
- Third-party carrier management

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 09:53:54 -06:00

284 lines
9.3 KiB
Markdown
Raw Blame History

# 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*
Reference in New Issue View Git Blame Copy Permalink