rckrdmrd/erp-transportistas-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
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

289 lines
9.9 KiB
Markdown
Raw Permalink 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*
Reference in New Issue View Git Blame Copy Permalink