erp-transportistas-v2/orchestration/PLAN-DESARROLLO-REUTILIZACION.md

PLAN DE DESARROLLO - ERP Transportistas

Proyecto: erp-transportistas Directiva: @SIMCO-REUSE + @DECISION-TREE Fecha: 2026-01-25 Objetivo: Maximizar reutilización de código existente, minimizar tokens

---

PRINCIPIO RECTOR

"Si existe código >=70% similar, SIEMPRE COPIAR"

Consultar @REUSABLE-CODE-INVENTORY antes de generar cualquier código.

---

RESUMEN DE ESTRATEGIA

Nivel	Accion	Ahorro Tokens	Modulos
100% Copia Directa	Copiar sin modificar	~90%	auth, users, ai, payment-terminals, mcp-core
70-95% Copiar+Adaptar	Copiar y extender	~70%	customers->shippers, inventory->refacciones
50-70% Patron+Generar	Usar estructura	~50%	OT, viajes, flota, tracking
<30% Generar Nuevo	Crear desde cero	0%	Carta Porte, HOS, logica especifica

---

FASE 0: COPIAR MODULOS BASE (100% Reutilizable)

0.1 Copiar auth (100%)

Origen: projects/erp-core/backend/src/modules/auth Destino: projects/erp-transportistas/backend/src/modules/auth

# Ejecutar
cp -r projects/erp-core/backend/src/modules/auth \
      projects/erp-transportistas/backend/src/modules/

# Verificar
cd projects/erp-transportistas/backend
npm run build && npm run lint

Modificaciones: Ninguna (codigo identico) Tokens ahorrados: ~1200 lineas * 90% = ~1080 lineas

---

0.2 Copiar users (100%)

Origen: projects/erp-core/backend/src/modules/users Destino: projects/erp-transportistas/backend/src/modules/users

cp -r projects/erp-core/backend/src/modules/users \
      projects/erp-transportistas/backend/src/modules/

Modificaciones: Ninguna Tokens ahorrados: ~800 lineas * 90% = ~720 lineas

---

0.3 Copiar tenants (100%)

Origen: projects/erp-core/backend/src/modules/tenants Destino: projects/erp-transportistas/backend/src/modules/tenants

cp -r projects/erp-core/backend/src/modules/tenants \
      projects/erp-transportistas/backend/src/modules/

Modificaciones: Ninguna (empresas transportistas = tenants) Tokens ahorrados: ~600 lineas * 90% = ~540 lineas

---

0.4 Copiar ai (95%)

Origen: projects/erp-core/backend/src/modules/ai Destino: projects/erp-transportistas/backend/src/modules/ai

cp -r projects/erp-core/backend/src/modules/ai \
      projects/erp-transportistas/backend/src/modules/

Modificaciones: Agregar prompts especificos de transporte (opcional, fase 2) Tokens ahorrados: ~600 lineas * 85% = ~510 lineas

---

0.5 Copiar payment-terminals (100%)

Origen: projects/erp-core/backend/src/modules/payment-terminals Destino: projects/erp-transportistas/backend/src/modules/payment-terminals

cp -r projects/erp-core/backend/src/modules/payment-terminals \
      projects/erp-transportistas/backend/src/modules/

Modificaciones: Ninguna Tokens ahorrados: ~800 lineas * 90% = ~720 lineas

---

0.6 Copiar audit (100%)

Origen: projects/erp-core/backend/src/modules/audit Destino: projects/erp-transportistas/backend/src/modules/audit

cp -r projects/erp-core/backend/src/modules/audit \
      projects/erp-transportistas/backend/src/modules/

Modificaciones: Ninguna Tokens ahorrados: ~400 lineas * 90% = ~360 lineas

---

0.7 Copiar notifications (100%)

Origen: projects/erp-core/backend/src/modules/notifications Destino: projects/erp-transportistas/backend/src/modules/notifications

cp -r projects/erp-core/backend/src/modules/notifications \
      projects/erp-transportistas/backend/src/modules/

Modificaciones: Ninguna Tokens ahorrados: ~500 lineas * 90% = ~450 lineas

---

0.8 Copiar mcp-core (85%)

Origen: projects/erp-core/backend/src/modules/mcp/core Destino: projects/erp-transportistas/backend/src/modules/mcp/core

# Copiar core (sin tools)
mkdir -p projects/erp-transportistas/backend/src/modules/mcp
cp -r projects/erp-core/backend/src/modules/mcp/core \
      projects/erp-transportistas/backend/src/modules/mcp/

Modificaciones: Crear tools especificos de transporte en fase 2 Tokens ahorrados: ~1000 lineas * 85% = ~850 lineas

---

0.9 Copiar shared/ completo (100%)

Origen: projects/erp-core/backend/src/shared Destino: projects/erp-transportistas/backend/src/shared

cp -r projects/erp-core/backend/src/shared \
      projects/erp-transportistas/backend/src/

Contenido:

• base.entity.ts
• multi-tenant.entity.ts
• auditable.entity.ts
• base.service.ts
• middlewares/
• errors/
• types/
• utils/

Tokens ahorrados: ~1500 lineas * 90% = ~1350 lineas

---

FASE 1: COPIAR Y ADAPTAR (70-95% Reutilizable)

1.1 Copiar partners -> adaptar a shippers/consignees (80%)

Origen: projects/erp-core/backend/src/modules/partners Destino: projects/erp-transportistas/backend/src/modules/partners

cp -r projects/erp-core/backend/src/modules/partners \
      projects/erp-transportistas/backend/src/modules/

Adaptaciones necesarias:

1. Entity partner.entity.ts - Agregar campos de transporte:

// Campos adicionales para shipper/consignee
@Column({ nullable: true })
codigo_sct: string;  // Codigo SCT si es transportista

@Column({ type: 'enum', enum: TipoPartnerTransporte })
tipo_partner: TipoPartnerTransporte; // SHIPPER | CONSIGNEE | CARRIER | AMBOS

@Column({ type: 'jsonb', nullable: true })
ubicaciones_frecuentes: UbicacionFrecuente[];  // Origenes/destinos comunes

@Column({ type: 'jsonb', nullable: true })
requisitos_seguridad: RequisitoSeguridad[];  // GPS, sellos, escolta

2. Service partners.service.ts - Agregar metodos:

async findShippers(tenantId: string) { }
async findConsignees(tenantId: string) { }
async findCarriers(tenantId: string) { }
async getUbicacionesFrecuentes(partnerId: string, tenantId: string) { }

Tokens ahorrados: ~600 lineas base * 80% = ~480 lineas

---

1.2 Copiar inventory -> adaptar a refacciones (75%)

Origen: projects/erp-core/backend/src/modules/inventory Destino: projects/erp-transportistas/backend/src/modules/inventory

cp -r projects/erp-core/backend/src/modules/inventory \
      projects/erp-transportistas/backend/src/modules/

Adaptaciones necesarias:

1. Entity product.entity.ts - Campos de refacciones:

// Campos adicionales para refacciones de flota
@Column({ nullable: true })
numero_parte: string;  // Numero de parte fabricante

@Column({ type: 'enum', enum: TipoRefaccion, nullable: true })
tipo_refaccion: TipoRefaccion;  // MOTOR | FRENOS | LLANTAS | SUSPENSION | etc

@Column({ type: 'uuid[]', nullable: true })
unidades_compatibles: string[];  // Unidades donde aplica

2. Service inventory.service.ts - Metodos de mantenimiento:

async getRefaccionesParaUnidad(unidadId: string, tenantId: string) { }
async reservarParaOrdenTrabajo(items: ReservaItem[], ordenId: string) { }

Tokens ahorrados: ~1500 lineas base * 75% = ~1125 lineas

---

1.3 Copiar financial -> adaptar a costeo transporte (80%)

Origen: projects/erp-core/backend/src/modules/financial Destino: projects/erp-transportistas/backend/src/modules/financial

cp -r projects/erp-core/backend/src/modules/financial \
      projects/erp-transportistas/backend/src/modules/

Adaptaciones necesarias:

• Cuentas contables especificas de transporte
• Centros de costo por unidad/ruta
• Reportes de rentabilidad por viaje

Tokens ahorrados: ~1200 lineas base * 80% = ~960 lineas

---

FASE 2: USAR PATRON + GENERAR (50-70% Reutilizable)

2.1 Modulo gestion-flota (MAI-011) - COPIAR estructura de products

Patron origen: projects/erp-core/backend/src/modules/products Destino: projects/erp-transportistas/backend/src/modules/gestion-flota

# 1. Copiar estructura
cp -r projects/erp-core/backend/src/modules/products \
      projects/erp-transportistas/backend/src/modules/gestion-flota

# 2. Renombrar archivos
cd projects/erp-transportistas/backend/src/modules/gestion-flota
mv products.controller.ts flota.controller.ts
mv products.service.ts flota.service.ts
mv product.entity.ts unidad.entity.ts

# 3. Buscar y reemplazar
find . -type f -name "*.ts" -exec sed -i 's/Product/Unidad/g' {} \;
find . -type f -name "*.ts" -exec sed -i 's/product/unidad/g' {} \;
find . -type f -name "*.ts" -exec sed -i 's/products/flota/g' {} \;

Entities a crear (heredar de MultiTenantEntity):

• unidad.entity.ts - Tractora, remolque, caja
• operador.entity.ts - Conductores
• licencia-operador.entity.ts - Licencias y vigencias
• documento-unidad.entity.ts - Permisos, polizas, verificaciones

Tokens ahorrados: ~50% estructura + generar campos especificos

---

2.2 Modulo ordenes-transporte (MAI-003) - COPIAR estructura de sales

Patron origen: projects/erp-core/backend/src/modules/sales Destino: projects/erp-transportistas/backend/src/modules/ordenes-transporte

# 1. Copiar estructura
cp -r projects/erp-core/backend/src/modules/sales \
      projects/erp-transportistas/backend/src/modules/ordenes-transporte

# 2. Renombrar
cd projects/erp-transportistas/backend/src/modules/ordenes-transporte
mv sale.entity.ts orden-transporte.entity.ts
mv sales.service.ts ordenes-transporte.service.ts
mv sales.controller.ts ordenes-transporte.controller.ts

# 3. Buscar y reemplazar
find . -type f -name "*.ts" -exec sed -i 's/Sale/OrdenTransporte/g' {} \;
find . -type f -name "*.ts" -exec sed -i 's/sale/ordenTransporte/g' {} \;

Entities adicionales (generar):

• embarque.entity.ts - Agrupacion de OTs
• parada-viaje.entity.ts - Multi-paradas
• restriccion-ot.entity.ts - Restricciones logisticas

---

2.3 Modulo tracking (MAI-006) - SIN patron similar, GENERAR con estructura

Estrategia: Usar module-structure pattern + generar entities especificas

# 1. Crear estructura desde template
mkdir -p projects/erp-transportistas/backend/src/modules/tracking/{controllers,services,entities,dto}

# 2. Copiar base.service.ts para heredar
# Ya copiado en shared/services/

# 3. Generar entities especificas (no existe patron)

Entities a generar (100% nuevo):

• evento-tracking.entity.ts
• geocerca.entity.ts
• alerta.entity.ts
• posicion-gps.entity.ts

Services a generar:

• tracking.service.ts (hereda de BaseService)
• gps-provider.service.ts (integracion)
• geocerca.service.ts
• alertas.service.ts

---

2.4 Modulo viajes (parte de MAI-005) - COPIAR de projects

Patron origen: projects/erp-core/backend/src/modules/projects Destino: projects/erp-transportistas/backend/src/modules/viajes

cp -r projects/erp-core/backend/src/modules/projects \
      projects/erp-transportistas/backend/src/modules/viajes

# Renombrar Project -> Viaje
find . -type f -name "*.ts" -exec sed -i 's/Project/Viaje/g' {} \;

Entities adicionales:

• checklist-viaje.entity.ts
• sello-viaje.entity.ts
• evidencia-viaje.entity.ts

---

FASE 3: GENERAR NUEVO (Logica Especifica del Giro)

3.1 Modulo carta-porte-cfdi (MAE-016) - 100% NUEVO

Razon: Logica especifica de CFDI + Carta Porte 3.1, no existe en otros proyectos.

Entities a generar:

• carta-porte.entity.ts
• ubicacion-carta-porte.entity.ts
• mercancia-carta-porte.entity.ts
• autotransporte-carta-porte.entity.ts

Services a generar:

• carta-porte.service.ts - Armado de complemento
• carta-porte-validator.service.ts - Validaciones SAT
• pac-integration.service.ts - Timbrado con PAC

IMPORTANTE: Documentar en REUSABLE-CODE-INVENTORY para futuros verticales de logistica.

---

3.2 Modulo tarifas-transporte (MAI-002) - 80% NUEVO

Patron parcial: Copiar pricing de erp-retail si existe, o generar.

Entities a generar:

• tarifa.entity.ts - Precio por lane/servicio/equipo
• recargo.entity.ts - Fuel surcharge, detention, maniobras
• contrato-tarifa.entity.ts - Tarifas por cliente
• lane.entity.ts - Rutas origen-destino

---

3.3 Modulo combustible-gastos (MAI-012) - 90% NUEVO

Entities a generar:

• carga-combustible.entity.ts
• cruce-peaje.entity.ts
• gasto-viaje.entity.ts
• viatico.entity.ts

---

RESUMEN DE TOKENS AHORRADOS

Fase	Modulos	Lineas Base	% Ahorro	Lineas Ahorradas
0	9 modulos base	~8,000	90%	~7,200
1	3 modulos adaptar	~3,300	75%	~2,475
2	4 modulos patron	~2,000	50%	~1,000
3	3 modulos nuevos	~3,000	0%	0
TOTAL	19 modulos	~16,300	~65%	~10,675

Conclusion: Al seguir la directiva @SIMCO-REUSE, ahorramos aproximadamente 65% de tokens en el desarrollo del backend.

---

CHECKLIST DE EJECUCION

Fase 0 - Copiar Base (COMPLETADO 2026-01-25)

• Copiar shared/
• Copiar auth
• Copiar users
• Copiar tenants
• Copiar ai
• Copiar payment-terminals
• Copiar audit
• Copiar notifications
• Copiar mcp (completo)
• Copiar config/
• Copiar billing-usage
• Copiar branches
• Copiar companies
• Copiar core
• Build + lint

Fase 1 - Adaptar (COMPLETADO 2026-01-25)

• Copiar partners
• Copiar inventory
• Copiar financial
• Adaptar partners → shippers/consignees (TipoPartnerTransporte, UbicacionFrecuente, RequisitoSeguridad)
• Adaptar inventory → refacciones (pendiente campos específicos)
• Adaptar financial → costeo transporte (pendiente cuentas transporte)
• Build + lint

Fase 2 - Patron + Generar (PARCIALMENTE COMPLETADO 2026-01-25)

• Crear gestion-flota desde products
• Crear ordenes-transporte desde sales
• Crear viajes desde projects
• Crear tracking (estructura base)
• Implementar entities gestion-flota (Unidad, Operador)
• Implementar entities ordenes-transporte (OrdenTransporte)
• Implementar entities tracking (EventoTracking, Geocerca)
• Implementar entities viajes (Viaje, ParadaViaje)
• Build + lint

Fase 3 - Generar Nuevo (EN PROGRESO 2026-01-25)

• Crear estructura carta-porte
• Crear estructura tarifas-transporte
• Crear estructura combustible-gastos
• DDL completo 01-08 (transport, fleet, tracking, fuel, maintenance, carriers, billing, compliance)
• Implementar entities carta-porte
• Implementar entities tarifas-transporte
• Implementar entities combustible-gastos
• Build + lint
• Documentar en REUSABLE-CODE-INVENTORY

---

COMANDO CONSOLIDADO FASE 0

# Ejecutar desde workspace-v2/
cd projects/erp-transportistas/backend/src

# Crear estructura
mkdir -p modules

# Copiar modulos base
cp -r ../../erp-core/backend/src/shared ./
cp -r ../../erp-core/backend/src/modules/auth ./modules/
cp -r ../../erp-core/backend/src/modules/users ./modules/
cp -r ../../erp-core/backend/src/modules/tenants ./modules/
cp -r ../../erp-core/backend/src/modules/ai ./modules/
cp -r ../../erp-core/backend/src/modules/payment-terminals ./modules/
cp -r ../../erp-core/backend/src/modules/audit ./modules/
cp -r ../../erp-core/backend/src/modules/notifications ./modules/

# Copiar MCP core
mkdir -p modules/mcp
cp -r ../../erp-core/backend/src/modules/mcp/core ./modules/mcp/

# Copiar config
cp -r ../../erp-core/backend/src/config ./

# Verificar
cd ..
npm install
npm run build
npm run lint

---

REFERENCIAS

• @SIMCO-REUSE - orchestration/directivas/simco/SIMCO-REUTILIZACION-CODIGO.md
• @DECISION-TREE - orchestration/directivas/simco/COPY-VS-GENERATE-DECISION-TREE.md
• @REUSABLE-CODE-INVENTORY - orchestration/inventarios/REUSABLE-CODE-INVENTORY.yml
• @PROPAGATION-RULES - orchestration/directivas/simco/PROPAGATION-RULES.md

---

Plan de Desarrollo ERP Transportistas - Optimizado para Reutilizacion Tokens estimados ahorrados: ~65% (~10,675 lineas de codigo)