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

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

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

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

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

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

```typescript
@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

```sql
-- 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*