rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
04c2db7bbc
erp-transportistas-v2/CLAUDE.md
Adrian Flores Cortes 04c2db7bbc [TASK-2026-02-06-ESTANDARIZACION-ESTRUCTURA-PROYECTOS] refactor: Migrate to canonical apps/ structure (ADR-0011) 
- backend/ → apps/backend/, frontend/ → apps/frontend-web/, database/ → apps/database/
- mobile/ → apps/frontend-mobile/
- Updated .gitmodules, CLAUDE.md v2.0.0
- Added apps/_MAP.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-06 10:30:14 -06:00

9.9 KiB
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: 2.0.0 Actualizado: 2026-02-06 ADR Vinculante: ADR-0011 (Estructura Canonica apps/)

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 CANONICA (ADR-0011)

erp-transportistas/
├── apps/                          # Contenedor canonico de aplicaciones
│   ├── backend/                   # NestJS API (submodule → erp-transportistas-backend-v2)
│   │   └── src/modules/           # Modulos implementados
│   ├── frontend-web/              # React SPA (submodule → erp-transportistas-frontend-v2)
│   ├── frontend-mobile/           # React Native (submodule)
│   ├── database/                  # DDL PostgreSQL + PostGIS (submodule → erp-transportistas-database-v2)
│   │   └── ddl/                   # Archivos DDL
│   └── _MAP.md                    # Indice de aplicaciones
├── orchestration/                 # Sistema SIMCO local
├── docs/                          # Documentacion funcional
├── .claude/                       # Instrucciones Claude Code
└── .gitmodules                    # 4 submodules (backend, frontend-web, database, frontend-mobile)

IMPORTANTE: Todo desarrollo nuevo DEBE ir dentro de apps/. No crear archivos en raiz.

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 → apps/backend/src/
  • @FRONTEND → apps/frontend-web/src/
  • @DDL → apps/database/ddl/
  • @MOBILE → apps/frontend-mobile/
  • @APPS-MAP → apps/_MAP.md
  • @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 v2.0.0 - Sistema SIMCO v4.0.0 Estructura migrada a apps/ canonico: 2026-02-06