260 lines
9.3 KiB
Markdown
260 lines
9.3 KiB
Markdown
# Sprint 2 — Etapa 1: Migración del modelo de recursos
|
||
|
||
> **Tipo:** dominio puro + persistencia. Sin UI. Sin cambios visuales.
|
||
> **Objetivo:** migrar `ActivityResourceAssignment.utilizationPercent` → `utilizationMinutes + units`, actualizar la fórmula de simulación, incrementar Dexie a v3, y garantizar que los datos existentes se preservan correctamente.
|
||
> **Resultado esperado:** tests verdes + reporte de archivos modificados. La UI en Etapas 2–3.
|
||
|
||
---
|
||
|
||
## Contexto imprescindible
|
||
|
||
### Estado actual del modelo (lo que vas a encontrar en el código)
|
||
|
||
```typescript
|
||
// src/domain/types.ts — HOY
|
||
interface ActivityResourceAssignment {
|
||
resourceId: UUID
|
||
utilizationPercent: number // 0–1, fracción del tiempo de la actividad
|
||
}
|
||
|
||
// Fórmula actual en src/domain/simulation.ts
|
||
const hoursUsed = (executionTimeMinutes / 60) * assignment.utilizationPercent
|
||
const cost = resource.costPerHour * hoursUsed * execProb
|
||
```
|
||
|
||
```typescript
|
||
// src/domain/schemas.ts — HOY
|
||
export const ActivityResourceAssignmentSchema = z.object({
|
||
resourceId: z.string().uuid(),
|
||
utilizationPercent: z.number().min(0).max(1),
|
||
})
|
||
```
|
||
|
||
```typescript
|
||
// src/persistence/db.ts — HOY
|
||
// Dexie versión 2 (v1 original + v2 de Sprint 1)
|
||
// La tabla 'resources' ya existe desde v1.
|
||
// ActivityResourceAssignment está embebido en Activity (no es tabla propia).
|
||
```
|
||
|
||
### Lo que NO existe todavía (no confundir con lo anterior)
|
||
|
||
- No existe tabla `resourceAssignments` separada. Los assignments están embebidos en el array `Activity.assignedResources`.
|
||
- No existe campo `utilizationMinutes`. Solo existe `utilizationPercent`.
|
||
- No existe campo `units`. Hay que agregarlo.
|
||
|
||
---
|
||
|
||
## Cambios requeridos
|
||
|
||
### 1. `src/domain/types.ts`
|
||
|
||
Reemplazar `ActivityResourceAssignment`:
|
||
|
||
```typescript
|
||
// ANTES
|
||
export interface ActivityResourceAssignment {
|
||
resourceId: UUID
|
||
utilizationPercent: number
|
||
}
|
||
|
||
// DESPUÉS
|
||
export interface ActivityResourceAssignment {
|
||
resourceId: UUID
|
||
utilizationMinutes: number // minutos que este recurso dedica por ejecución (independiente del tiempo de la actividad)
|
||
units: number // cantidad de unidades del recurso (ej: 2 impresoras). Default: 1.
|
||
}
|
||
```
|
||
|
||
El tipo `Resource` NO cambia. Solo cambia `ActivityResourceAssignment`.
|
||
|
||
### 2. `src/domain/schemas.ts`
|
||
|
||
Reemplazar `ActivityResourceAssignmentSchema`:
|
||
|
||
```typescript
|
||
// ANTES
|
||
export const ActivityResourceAssignmentSchema = z.object({
|
||
resourceId: z.string().uuid(),
|
||
utilizationPercent: z.number().min(0).max(1),
|
||
})
|
||
|
||
// DESPUÉS
|
||
export const ActivityResourceAssignmentSchema = z.object({
|
||
resourceId: z.string().uuid(),
|
||
utilizationMinutes: z.number().min(0, 'Los minutos no pueden ser negativos'),
|
||
units: z.number().int().min(1, 'Las unidades deben ser al menos 1').default(1),
|
||
})
|
||
```
|
||
|
||
### 3. `src/domain/simulation.ts`
|
||
|
||
Actualizar la fórmula de costo de recursos. Buscar el bloque que calcula `hoursUsed` y reemplazarlo:
|
||
|
||
```typescript
|
||
// ANTES
|
||
const hoursUsed = (executionTimeMinutes / 60) * assignment.utilizationPercent
|
||
const cost = resource.costPerHour * hoursUsed * execProb
|
||
|
||
// DESPUÉS
|
||
const hoursUsed = (assignment.utilizationMinutes / 60) * assignment.units
|
||
const cost = resource.costPerHour * hoursUsed * execProb
|
||
```
|
||
|
||
El `execProb` se mantiene igual — sigue siendo la probabilidad de ejecución del nodo en el grafo BPMN. El costo esperado del recurso por ejecución del proceso es `costPerHour × utilizationMinutes/60 × units × execProb`.
|
||
|
||
También actualizar la línea de acumulación de minutos por recurso (buscar `resourceTotals`):
|
||
|
||
```typescript
|
||
// ANTES
|
||
minutes: prev.minutes + activity.executionTimeMinutes * assignment.utilizationPercent * execProb,
|
||
|
||
// DESPUÉS
|
||
minutes: prev.minutes + assignment.utilizationMinutes * assignment.units * execProb,
|
||
```
|
||
|
||
### 4. `src/persistence/db.ts`
|
||
|
||
Agregar versión 3 con función de upgrade. La migración convierte los assignments embebidos en Activity:
|
||
|
||
```typescript
|
||
this.version(3)
|
||
.stores({
|
||
// Los stores no cambian — ActivityResourceAssignment está embebido en Activity, no es tabla propia
|
||
processes: 'id, name, updatedAt',
|
||
activities: 'id, processId, bpmnElementId',
|
||
gateways: 'id, processId, bpmnElementId',
|
||
resources: 'id, processId, name',
|
||
simulations: 'id, processId, executedAt',
|
||
})
|
||
.upgrade(async (tx) => {
|
||
// Migrar assignedResources de cada actividad: utilizationPercent → utilizationMinutes + units
|
||
await tx.table('activities').toCollection().modify((act) => {
|
||
if (!Array.isArray(act.assignedResources)) {
|
||
act.assignedResources = []
|
||
return
|
||
}
|
||
act.assignedResources = act.assignedResources.map((assignment: Record<string, unknown>) => {
|
||
if ('utilizationPercent' in assignment) {
|
||
// Heurística de conversión: minutos = round(executionTimeMinutes × utilizationPercent)
|
||
// Si executionTimeMinutes no está disponible o es 0, usar 0 (conservador)
|
||
const execMinutes = typeof act.executionTimeMinutes === 'number' ? act.executionTimeMinutes : 0
|
||
const utilizationMinutes = Math.round(execMinutes * (assignment.utilizationPercent as number))
|
||
return {
|
||
resourceId: assignment.resourceId,
|
||
utilizationMinutes,
|
||
units: 1,
|
||
}
|
||
}
|
||
// Ya está en el nuevo formato (por si se corre la migración dos veces)
|
||
if ('utilizationMinutes' in assignment) {
|
||
return {
|
||
resourceId: assignment.resourceId,
|
||
utilizationMinutes: assignment.utilizationMinutes ?? 0,
|
||
units: assignment.units ?? 1,
|
||
}
|
||
}
|
||
// Fallback defensivo
|
||
return { resourceId: assignment.resourceId, utilizationMinutes: 0, units: 1 }
|
||
})
|
||
})
|
||
})
|
||
```
|
||
|
||
**Importante:** no eliminar las versiones 1 y 2 anteriores. Dexie requiere el historial completo de versiones.
|
||
|
||
### 5. Puntos de inicialización en `src/features/import/ImportPage.tsx`
|
||
|
||
Buscar donde se inicializa una nueva actividad (al importar BPMN). Hay una línea similar a:
|
||
```typescript
|
||
assignedResources: [],
|
||
```
|
||
Esto está bien — un array vacío es válido con el nuevo modelo. No requiere cambio, pero verificar que no haya ningún lugar que inicialice con `utilizationPercent`.
|
||
|
||
**Grep de verificación:** buscar en todo `src/` cualquier referencia a `utilizationPercent`. Al terminar la etapa, esta búsqueda debe devolver cero resultados.
|
||
|
||
---
|
||
|
||
## Tests requeridos
|
||
|
||
### Tests unitarios — `tests/domain/simulation.test.ts`
|
||
|
||
Agregar los siguientes casos al archivo existente (no borrar los tests actuales):
|
||
|
||
```
|
||
describe('recursos con modelo utilizationMinutes + units', () => {
|
||
test('actividad sin recursos: costo = directCostFixed')
|
||
test('actividad con 1 recurso: costo = fijo + costPerHour × utilizationMinutes/60 × units × execProb')
|
||
test('actividad con 2 recursos: costo = fijo + suma de costos de recursos')
|
||
test('units = 2: costo de recurso se duplica')
|
||
test('utilizationMinutes = 0: el recurso no agrega costo')
|
||
test('resource no encontrado en el mapa: se ignora sin lanzar error')
|
||
})
|
||
```
|
||
|
||
### Test de migración — `tests/integration/` (crear archivo nuevo `db-migration-v3.test.ts`)
|
||
|
||
```
|
||
test('migración v2→v3: actividad con utilizationPercent se convierte a utilizationMinutes correctamente')
|
||
test('migración v2→v3: actividad sin assignedResources mantiene array vacío')
|
||
test('migración v2→v3: actividad con assignedResources vacío no falla')
|
||
test('migración v2→v3: el costo calculado después de la migración es aproximadamente igual al anterior')
|
||
// El costo debe ser igual ± redondeo de Math.round()
|
||
```
|
||
|
||
---
|
||
|
||
## Verificaciones finales obligatorias
|
||
|
||
Antes de reportar la etapa como completa:
|
||
|
||
1. **Grep de limpieza:** `grep -r "utilizationPercent" src/` — debe devolver 0 resultados.
|
||
2. **Build limpio:** `npm run build` sin errores de TypeScript.
|
||
3. **Tests:** `npm run test` — todos los tests (existentes + nuevos) deben pasar.
|
||
4. **Smoke test manual:** cargar la app en dev (`npm run dev`), abrir un proceso existente con recursos, verificar que no crashea y que el workspace carga.
|
||
|
||
---
|
||
|
||
## Alcance estricto — lo que NO entra en esta etapa
|
||
|
||
- ❌ Cambios en `ActivityPanel.tsx` (UI del panel de actividad) — Etapa 2
|
||
- ❌ Cambios en `ResourcesPanel.tsx` — Etapa 2 si necesita ajustes
|
||
- ❌ Cambios en `ActivitiesTable.tsx` ni en el reporte — Etapa 3
|
||
- ❌ Cambios en PDFs — Etapa 5
|
||
- ❌ Edición inline de proceso/cliente — Etapa 4
|
||
- ❌ CumulativeSavingsChart, payback label, badge — Etapa 3
|
||
|
||
Si al hacer el grep de limpieza encontrás referencias a `utilizationPercent` en componentes UI, **no las corrijas en esta etapa**. Documentalas en el reporte para que Etapa 2 las tome.
|
||
|
||
---
|
||
|
||
## Reporte esperado al terminar
|
||
|
||
```
|
||
## Etapa 1 completada
|
||
|
||
### Archivos modificados
|
||
- src/domain/types.ts — ActivityResourceAssignment: utilizationPercent → utilizationMinutes + units
|
||
- src/domain/schemas.ts — ActivityResourceAssignmentSchema actualizado
|
||
- src/domain/simulation.ts — fórmula de costo de recursos actualizada
|
||
- src/persistence/db.ts — versión 3 con migración
|
||
|
||
### Archivos creados
|
||
- tests/integration/db-migration-v3.test.ts
|
||
|
||
### Tests
|
||
- X tests unitarios nuevos (todos verdes)
|
||
- X tests de migración (todos verdes)
|
||
- X tests previos (todos siguen verdes)
|
||
|
||
### Grep de limpieza
|
||
- "utilizationPercent" en src/: 0 resultados ✅
|
||
(o lista de archivos UI pendientes para Etapa 2)
|
||
|
||
### Build
|
||
- npm run build: ✅ sin errores TypeScript
|
||
|
||
### Notas
|
||
[cualquier hallazgo relevante para Etapas siguientes]
|
||
```
|