23 KiB
US-PROJ-002: Transiciones de Estado de Proyectos
Épica: MAI-002 - Proyectos y Estructura de Obra Sprint: Sprint 3 Story Points: 5 SP Prioridad: P0 (Crítica) Estimación: 2-3 días Versión: 1.0 Fecha: 2025-11-17
Historia de Usuario
Como Director de Proyectos Quiero cambiar el estado de un proyecto siguiendo un flujo controlado y validado Para reflejar el avance del ciclo de vida del proyecto y asegurar que solo se realicen transiciones válidas con las condiciones cumplidas
Contexto de Negocio
Los proyectos de construcción pasan por un ciclo de vida bien definido:
Licitación → Adjudicado → Ejecución → Entregado → Cerrado
Cada transición de estado debe:
- Validarse contra reglas de negocio
- Actualizar fechas automáticamente
- Verificar condiciones previas (checklist)
- Emitir notificaciones a equipo relevante
- Quedar registrada en auditoría (quién, cuándo, por qué)
No se permiten saltos de estado ni regresiones (excepto casos especiales con aprobación).
Criterios de Aceptación
✅ AC1: Visualización de Estado Actual y Permitidos
Dado que estoy viendo el detalle de un proyecto Entonces debo ver:
-
Badge visual del estado actual con color distintivo:
- 🟰 Licitación: Gris (#6B7280)
- 🔵 Adjudicado: Azul (#3B82F6)
- 🟢 Ejecución: Verde (#10B981)
- 🟣 Entregado: Púrpura (#8B5CF6)
- ⚫ Cerrado: Gris Oscuro (#374151)
-
Botón "Cambiar Estado" (solo visible para Director/Admin)
-
Historial de cambios de estado (timeline):
📅 15/11/2025 10:30 - Juan Pérez cambió estado a "Ejecución" Nota: "Licencias obtenidas, inicia construcción" 📅 10/10/2025 09:15 - María López cambió estado a "Adjudicado" Nota: "Contrato firmado con INFONAVIT"
✅ AC2: Flujo de Cambio de Estado
Dado que soy Director o Admin Y el proyecto está en estado "Adjudicado" Cuando hago clic en "Cambiar Estado" Entonces debo ver un modal con:
┌───────────────────────────────────────────────────────────┐
│ Cambiar Estado del Proyecto │
│ PROJ-2025-001 - Fraccionamiento Los Pinos │
├───────────────────────────────────────────────────────────┤
│ │
│ Estado actual: 🔵 Adjudicado │
│ │
│ Nuevo estado: │
│ ⚪ Licitación (no permitido - regresión) │
│ 🔵 Adjudicado (estado actual) │
│ 🟢 Ejecución ✓ PERMITIDO │
│ ⚪ Entregado (no permitido - debe pasar por Ejecución) │
│ ⚪ Cerrado (no permitido - debe pasar por Entregado) │
│ │
│ Seleccionado: 🟢 Ejecución │
│ │
│ ✅ Condiciones para cambiar a Ejecución: │
│ ☑ Licencia de construcción obtenida │
│ ☑ Equipo de proyecto asignado │
│ ☑ Estructura del proyecto creada │
│ ☐ Fecha de inicio actualizada │
│ │
│ Notas del cambio (obligatorio): │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Licencias obtenidas, inicio de construcción │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Actualizar fecha de inicio real: [📅 2025-11-15] │
│ │
│ [Cancelar] [Cambiar Estado] │
└───────────────────────────────────────────────────────────┘
Y solo debo poder seleccionar estados permitidos según flujo Y debo completar el checklist de condiciones (si aplica) Y debo ingresar nota obligatoria del cambio
✅ AC3: Validación de Transiciones Permitidas
Reglas de flujo:
| Estado Actual | Estados Permitidos | Condiciones |
|---|---|---|
| Licitación | Adjudicado | - Monto de contrato definido - Cliente asignado |
| Adjudicado | Ejecución | - Licencia de construcción - Equipo asignado - Estructura creada |
| Ejecución | Entregado | - Avance físico >= 95% - Finiquitos firmados - Acta de entrega |
| Entregado | Cerrado | - Garantías verificadas - Documentación completa - Cierre administrativo |
Dado que el proyecto está en "Ejecución" Cuando intento cambiar directamente a "Cerrado" Entonces sistema debe:
- Mostrar error: "No se puede cambiar de Ejecución a Cerrado directamente. Debe pasar por Entregado primero"
- No permitir seleccionar estado "Cerrado"
- Resaltar en rojo opciones no permitidas
✅ AC4: Actualización Automática de Fechas
Cuando cambio el estado del proyecto Entonces sistema debe actualizar fechas automáticamente:
| Transición | Campo Actualizado | Valor |
|---|---|---|
| Licitación → Adjudicado | awardDate |
Fecha actual |
| Adjudicado → Ejecución | actualStartDate |
Fecha seleccionada en modal |
| Ejecución → Entregado | deliveryDate |
Fecha seleccionada en modal |
| Entregado → Cerrado | closureDate |
Fecha actual |
Y si una fecha ya existe (transición repetida), debe preguntarse:
⚠️ Ya existe una fecha de inicio: 2025-06-01
¿Deseas actualizarla a la nueva fecha: 2025-11-15?
[Mantener fecha anterior] [Actualizar fecha]
✅ AC5: Checklist de Condiciones por Transición
Adjudicado → Ejecución:
- Licencia de construcción obtenida
- Equipo de proyecto asignado (mínimo: 1 Director, 1 Residente)
- Estructura del proyecto creada (al menos 1 etapa)
- Presupuesto aprobado (si módulo presupuesto está activo)
Ejecución → Entregado:
- Avance físico global >= 95%
- Finiquitos firmados
- Acta de entrega-recepción firmada
- Bitácora de obra cerrada
- Planos as-built entregados
Entregado → Cerrado:
- Garantías verificadas y vigentes
- Documentación legal completa
- Cierre administrativo aprobado
- Sin pendientes legales o financieros
- Archivo de proyecto respaldado
Cuando el checklist no está 100% completo Entonces sistema debe mostrar advertencia:
⚠️ Advertencia: 1 condición pendiente
No se ha marcado: "Planos as-built entregados"
¿Deseas continuar de todos modos? (requiere aprobación de Admin)
[Regresar a completar] [Continuar (Admin)]
Y si no soy Admin, no debo poder continuar sin checklist completo
✅ AC6: Notificaciones de Cambio de Estado
Cuando se cambia el estado de un proyecto Entonces sistema debe enviar notificaciones a:
| Destinatarios | Tipo | Ejemplo |
|---|---|---|
| Equipo del proyecto (todos) | Email + In-app | "El proyecto PROJ-2025-001 cambió a estado Ejecución" |
| Director del proyecto | Resumen detallado con próximos pasos | |
| Administradores | In-app | Registro de auditoría |
| Cliente (opcional) | Solo en transiciones: Ejecución, Entregado, Cerrado |
Contenido de notificación:
Asunto: Proyecto PROJ-2025-001 cambió a estado "Ejecución"
Proyecto: Fraccionamiento Los Pinos
Estado anterior: Adjudicado
Estado nuevo: Ejecución
Fecha de cambio: 15/11/2025 10:30
Cambiado por: Juan Pérez (Director)
Notas:
"Licencias obtenidas, inicio de construcción"
Fecha de inicio actualizada: 15/11/2025
Próximos pasos:
- Asignar cuadrillas de construcción
- Iniciar control de avances semanales
- Programar juntas de obra quincenales
[Ver Proyecto en Sistema]
✅ AC7: Historial y Auditoría de Cambios
Dado que estoy viendo el detalle de un proyecto Cuando accedo a la pestaña "Historial" Entonces debo ver un timeline completo de cambios de estado:
┌─────────────────────────────────────────────────────────────┐
│ Historial de Estados │
├─────────────────────────────────────────────────────────────┤
│ │
│ ● 🟢 Ejecución │
│ 15/11/2025 10:30 - Juan Pérez │
│ "Licencias obtenidas, inicio de construcción" │
│ Actualizado: actualStartDate → 2025-11-15 │
│ │
│ ● 🔵 Adjudicado │
│ 10/10/2025 09:15 - María López │
│ "Contrato firmado con INFONAVIT" │
│ Actualizado: awardDate → 2025-10-10 │
│ │
│ ● 🟰 Licitación │
│ 01/09/2025 14:00 - Sistema │
│ "Proyecto creado" │
│ │
└─────────────────────────────────────────────────────────────┘
Y cada registro debe incluir:
- Timestamp exacto
- Usuario que realizó el cambio
- Estado anterior y nuevo
- Notas/motivo del cambio
- Campos actualizados automáticamente
✅ AC8: Permisos por Rol
| Acción | Director | Residente | Ingeniero | Supervisor | Admin |
|---|---|---|---|---|---|
| Cambiar estado | ✅ | ❌ | ❌ | ❌ | ✅ |
| Ver historial | ✅ | ✅ | ✅ | ✅ | ✅ |
| Forzar transición sin checklist | ❌ | ❌ | ❌ | ❌ | ✅ (con aprobación) |
| Revertir estado (regresión) | ❌ | ❌ | ❌ | ❌ | ✅ (con justificación) |
Dado que soy Residente Cuando intento cambiar el estado de un proyecto Entonces sistema muestra error: "Solo Director y Admin pueden cambiar el estado del proyecto" Y el botón "Cambiar Estado" no debe estar visible
Escenarios de Prueba
Escenario 1: Transición Exitosa Adjudicado → Ejecución
Given proyecto en estado "Adjudicado" And soy Director autenticado And condiciones cumplidas:
- Licencia obtenida ✅
- Equipo asignado ✅
- Estructura creada ✅ When hago clic en "Cambiar Estado" And selecciono "Ejecución" And ingreso nota "Inicio de obra" And selecciono fecha inicio: 2025-11-15 And hago clic en "Cambiar Estado" Then estado cambia a "Ejecución" And actualStartDate = 2025-11-15 And se envían notificaciones a equipo And se registra en historial
Escenario 2: Transición Bloqueada por Falta de Condiciones
Given proyecto en estado "Adjudicado" And soy Director And NO hay equipo asignado When intento cambiar a "Ejecución" Then sistema muestra checklist con:
- ☐ Equipo de proyecto asignado (PENDIENTE) And muestra advertencia And botón "Cambiar Estado" está deshabilitado hasta completar
Escenario 3: Intento de Transición Inválida
Given proyecto en estado "Ejecución" When intento cambiar directamente a "Cerrado" Then opción "Cerrado" aparece deshabilitada (gris) And tooltip muestra: "Debe pasar por Entregado primero" And no puedo seleccionar "Cerrado"
Escenario 4: Regresión de Estado (Solo Admin)
Given proyecto en estado "Ejecución" And soy Admin When solicito revertir a "Adjudicado" (regresión) Then sistema muestra confirmación:
⚠️ ADVERTENCIA: Regresión de Estado
Estás a punto de revertir el proyecto de "Ejecución" a "Adjudicado".
Esta es una acción excepcional y quedará registrada en auditoría.
Motivo de regresión (obligatorio):
[_______________________________________________________]
[Cancelar] [Confirmar Regresión]
And registro queda marcado en auditoría como "REGRESIÓN"
Escenario 5: Notificación de Cambio de Estado
Given proyecto "PROJ-2025-001" cambia a "Ejecución" When se completa el cambio de estado Then equipo del proyecto recibe email And notificación in-app aparece en dashboard And cliente recibe email (si configurado)
Mockups / Wireframes
Modal de Cambio de Estado
┌───────────────────────────────────────────────────────────┐
│ Cambiar Estado del Proyecto [✕] │
│ PROJ-2025-001 - Fraccionamiento Los Pinos │
├───────────────────────────────────────────────────────────┤
│ │
│ Estado actual: 🔵 Adjudicado │
│ │
│ Selecciona nuevo estado: │
│ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ ⚪ Licitación [bloqueado]│ │
│ │ ● 🔵 Adjudicado [actual] │ │
│ │ ○ 🟢 Ejecución [permitido] │ │
│ │ ⚪ Entregado [bloqueado]│ │
│ │ ⚪ Cerrado [bloqueado]│ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ ✅ Condiciones para Ejecución: │
│ ☑ Licencia de construcción obtenida │
│ ☑ Equipo de proyecto asignado │
│ ☐ Estructura del proyecto creada [PENDIENTE] │
│ │
│ ⚠️ 1 condición pendiente │
│ │
│ Notas del cambio *: │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Fecha de inicio real: [📅 __/__/____] │
│ │
│ ☐ Notificar al cliente │
│ │
│ [Cancelar] [Cambiar Estado] │
│ [deshabilitado]│
└───────────────────────────────────────────────────────────┘
Timeline de Historial
┌─────────────────────────────────────────────────────────────┐
│ Historial de Estados [Exportar]│
├─────────────────────────────────────────────────────────────┤
│ │
│ ●──────────────────────────────────────────────── │
│ │ │
│ 🟢 Ejecución │
│ 15/11/2025 10:30 │
│ 👤 Juan Pérez (Director) │
│ 📝 "Licencias obtenidas, inicio de construcción" │
│ 🔄 actualStartDate → 2025-11-15 │
│ │ │
│ ●──────────────────────────────────────────────── │
│ │ │
│ 🔵 Adjudicado │
│ 10/10/2025 09:15 │
│ 👤 María López (Admin) │
│ 📝 "Contrato firmado con INFONAVIT" │
│ 🔄 awardDate → 2025-10-10 │
│ │ │
│ ●──────────────────────────────────────────────── │
│ │ │
│ 🟰 Licitación │
│ 01/09/2025 14:00 │
│ 👤 Sistema (Auto) │
│ 📝 "Proyecto creado" │
│ │
└─────────────────────────────────────────────────────────────┘
Definición de Done (DoD)
- Validación de transiciones según flujo implementada (backend)
- Modal de cambio de estado funcional (frontend)
- Checklist de condiciones por transición implementado
- Actualización automática de fechas funcionando
- Historial de cambios de estado visible y completo
- Notificaciones enviadas a equipo y cliente
- Permisos por rol implementados
- Tests unitarios de validación de transiciones (>80% coverage)
- Tests de integración para flujo completo de cambio
- Regresión de estado (solo Admin) implementada con auditoría
- Documentación de API actualizada (Swagger)
- Código revisado y aprobado
- Probado en QA con diferentes escenarios
- Sin issues de seguridad o performance
Notas Técnicas
Backend
Endpoint:
PUT /api/projects/:id/status
Body:
{
"newStatus": "ejecucion",
"notes": "Licencias obtenidas, inicio de construcción",
"actualStartDate": "2025-11-15",
"notifyClient": true,
"checklist": {
"licenseObtained": true,
"teamAssigned": true,
"structureCreated": true
}
}
Response:
{
"id": "uuid",
"status": "ejecucion",
"actualStartDate": "2025-11-15",
"updatedBy": "userId",
"updatedAt": "2025-11-15T10:30:00Z",
"statusHistory": [...]
}
Service Method:
async changeStatus(
id: string,
newStatus: ProjectStatus,
dto: ChangeStatusDto,
userId: string
): Promise<Project> {
const project = await this.findOne(id);
// Validate transition
this.validateStatusTransition(project.status, newStatus);
// Check conditions (if applicable)
await this.validateConditions(project, newStatus, dto.checklist);
// Update status and dates
const oldStatus = project.status;
project.status = newStatus;
this.updateStatusDates(project, newStatus, dto);
// Save and emit event
const updated = await this.projectRepo.save(project);
this.eventEmitter.emit('project.status_changed', {
project: updated,
oldStatus,
newStatus,
changedBy: userId,
notes: dto.notes
});
return updated;
}
Frontend
Components:
ChangeStatusModal.tsx- Modal de cambio de estadoStatusBadge.tsx- Badge visual de estadoStatusTimeline.tsx- Timeline de historialStatusChecklist.tsx- Checklist de condiciones
State Machine (XState - opcional):
const projectStatusMachine = createMachine({
id: 'projectStatus',
initial: 'licitacion',
states: {
licitacion: {
on: { ADJUDICAR: 'adjudicado' }
},
adjudicado: {
on: { INICIAR_EJECUCION: 'ejecucion' }
},
ejecucion: {
on: { ENTREGAR: 'entregado' }
},
entregado: {
on: { CERRAR: 'cerrado' }
},
cerrado: {
type: 'final'
}
}
});
Dependencias
Depende de:
- ✅ US-PROJ-001: Catálogo de Proyectos (necesita proyectos existentes)
- ✅ ET-PROJ-001: Especificación técnica de catálogo
Bloquea a:
- Ninguna (independiente)
Relacionado con:
- US-PROJ-007: Asignación de Equipo (condición para Ejecución)
- US-PROJ-003: Crear Estructura (condición para Ejecución)
Criterios de Aceptación del Product Owner
- Solo se permiten transiciones válidas según flujo definido
- Checklist de condiciones se verifica antes de permitir cambio
- Fechas se actualizan automáticamente según transición
- Historial completo y auditable de todos los cambios
- Notificaciones enviadas correctamente a equipo
- Solo Director y Admin pueden cambiar estados
- Regresiones solo permitidas para Admin con justificación
- Modal es intuitivo y muestra claramente opciones permitidas/bloqueadas
Fecha de generación: 2025-11-17 Autor: Equipo de Producto Aprobado por: Product Owner Estado: ✅ Ready for Development