erp-transportistas-v2/.claude/directivas/DIRECTIVAS-LOCALES.md

Directivas Locales - ERP Transportistas

Proyecto: erp-transportistas Sistema: SIMCO v4.0.0 Actualizado: 2026-01-25

---

DL-001: Dominio Transporte

Regla: Usar terminologia especifica del giro de transporte en todo el codigo y documentacion.

Terminologia Obligatoria

Termino	Significado	NO usar
OT (Orden de Transporte)	Solicitud de servicio	Pedido, Orden
Embarque	Agrupacion de OTs	Envio
Viaje	Ejecucion operativa	Ruta, Servicio
Unidad	Vehiculo (tractora/remolque/caja)	Camion, Trailer
Operador	Conductor	Chofer, Driver
POD	Proof of Delivery	Comprobante, Recibo
Carrier	Tercero subcontratado	Proveedor, Transportista
Lane	Ruta origen-destino	Corredor
Shipper	Cliente que envia	Remitente
Consignee	Cliente que recibe	Destinatario

Estados del Viaje

type EstadoViaje =
  | 'BORRADOR'
  | 'PLANEADO'
  | 'DESPACHADO'
  | 'EN_TRANSITO'
  | 'EN_DESTINO'
  | 'ENTREGADO'
  | 'CERRADO'
  | 'FACTURADO'
  | 'COBRADO';

---

DL-002: Coherencia con ERP Core

Regla: No modificar modulos heredados de erp-core. Solo extender.

Modulos Heredados (NO MODIFICAR)

• auth
• users
• roles
• tenants
• audit
• notifications
• billing
• plans
• webhooks
• feature_flags

Modulos que se EXTIENDEN

• partners → Agregar campos shipper/consignee
• catalogs → Agregar catalogos de transporte
• financial → Agregar cuentas de transporte
• sales → Servicios de transporte

Como Extender

// CORRECTO: Extender entity
@Entity({ schema: 'transport', name: 'partners_transport_ext' })
export class PartnerTransportExtension {
  @PrimaryColumn()
  partnerId: string;

  @Column({ nullable: true })
  codigoSCT: string;

  // ... campos especificos transporte
}

// INCORRECTO: Modificar entity de erp-core
// @Entity({ schema: 'public', name: 'partners' })
// export class Partner { ... } // NO HACER ESTO

---

DL-003: Cumplimiento Carta Porte

Regla: Todo viaje que requiera Carta Porte debe validar datos minimos antes de liberarse.

Datos Minimos Obligatorios

1. Ubicaciones

   • Origen con coordenadas
   • Destino(s) con coordenadas
   • Distancia recorrida

2. Mercancia

   • Clave de producto SAT
   • Descripcion
   • Cantidad y unidad
   • Peso en kg
   • Valor declarado

3. Autotransporte

   • Permiso SCT
   • Numero de permiso
   • Configuracion vehicular

4. Operador

   • RFC
   • Licencia federal
   • Nombre completo

5. Unidad

   • Placa
   • Ano modelo
   • Aseguradora y poliza

Validacion Pre-Despacho

// Validar antes de cambiar estado a DESPACHADO
async validateCartaPorteData(viajeId: string): Promise<ValidationResult> {
  const viaje = await this.findById(viajeId);
  const errors: string[] = [];

  // Validar ubicaciones
  if (!viaje.origen?.latitud || !viaje.origen?.longitud) {
    errors.push('Origen sin coordenadas');
  }

  // Validar mercancia
  if (!viaje.mercancias?.length) {
    errors.push('Sin mercancias');
  }

  // ... mas validaciones

  return { valid: errors.length === 0, errors };
}

---

DL-004: Tracking y Eventos

Regla: Todo evento de tracking debe registrarse con timestamp, geolocalizacion y fuente.

Tipos de Evento

type TipoEventoTracking =
  | 'SALIDA'           // Gate out
  | 'ARRIBO_ORIGEN'    // Llegada a punto de carga
  | 'INICIO_CARGA'
  | 'FIN_CARGA'
  | 'ARRIBO_DESTINO'   // Llegada a punto de entrega
  | 'INICIO_DESCARGA'
  | 'FIN_DESCARGA'
  | 'ENTREGA_POD'      // POD capturado
  | 'DESVIO'           // Fuera de ruta
  | 'PARADA'           // Parada no programada
  | 'INCIDENTE'        // Incidencia reportada
  | 'GPS_POSICION';    // Posicion automatica

Estructura de Evento

interface EventoTracking {
  id: string;
  viajeId: string;
  tipo: TipoEventoTracking;
  timestamp: Date;
  latitud: number;
  longitud: number;
  fuente: 'GPS' | 'APP_OPERADOR' | 'SISTEMA' | 'MANUAL';
  usuarioId?: string;
  observaciones?: string;
  evidencias?: string[];  // URLs de fotos/docs
}

---

DL-005: Multi-Tenancy

Regla: Todas las entidades del giro deben implementar aislamiento por tenant.

Patron Obligatorio

@Entity({ schema: 'transport', name: 'ordenes_transporte' })
@Index(['tenantId', 'codigo'], { unique: true })
export class OrdenTransporte {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  tenantId: string;  // OBLIGATORIO

  @Column({ unique: false }) // Unico por tenant, no global
  codigo: string;

  // ... mas campos

  @CreateDateColumn()
  createdAt: Date;

  @UpdateDateColumn()
  updatedAt: Date;

  @Column()
  createdById: string;
}

RLS en DDL

-- Habilitar RLS
ALTER TABLE transport.ordenes_transporte ENABLE ROW LEVEL SECURITY;

-- Politica de aislamiento
CREATE POLICY tenant_isolation ON transport.ordenes_transporte
  USING (tenant_id = current_setting('app.tenant_id')::uuid);

---

Directivas Locales ERP Transportistas - SIMCO v4.0.0