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`

```bash
# 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`

```bash
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`

```bash
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`

```bash
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`

```bash
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`

```bash
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`

```bash
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`

```bash
# 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`

```bash
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`

```bash
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:
```typescript
// 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:
```typescript
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`

```bash
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:
```typescript
// 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:
```typescript
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`

```bash
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`

```bash
# 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`

```bash
# 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

```bash
# 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`

```bash
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)
- [x] Copiar shared/
- [x] Copiar auth
- [x] Copiar users
- [x] Copiar tenants
- [x] Copiar ai
- [x] Copiar payment-terminals
- [x] Copiar audit
- [x] Copiar notifications
- [x] Copiar mcp (completo)
- [x] Copiar config/
- [x] Copiar billing-usage
- [x] Copiar branches
- [x] Copiar companies
- [x] Copiar core
- [ ] Build + lint

### Fase 1 - Adaptar (COMPLETADO 2026-01-25)
- [x] Copiar partners
- [x] Copiar inventory
- [x] Copiar financial
- [x] 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)
- [x] Crear gestion-flota desde products
- [x] Crear ordenes-transporte desde sales
- [x] Crear viajes desde projects
- [x] Crear tracking (estructura base)
- [x] Implementar entities gestion-flota (Unidad, Operador)
- [x] Implementar entities ordenes-transporte (OrdenTransporte)
- [x] Implementar entities tracking (EventoTracking, Geocerca)
- [ ] Implementar entities viajes (Viaje, ParadaViaje)
- [ ] Build + lint

### Fase 3 - Generar Nuevo (EN PROGRESO 2026-01-25)
- [x] Crear estructura carta-porte
- [x] Crear estructura tarifas-transporte
- [x] Crear estructura combustible-gastos
- [x] 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

```bash
# 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)*