# US-PROJ-003: Crear Estructura de Fraccionamiento Horizontal **Épica:** MAI-002 - Proyectos y Estructura de Obra **Sprint:** Sprint 4 **Story Points:** 8 SP **Prioridad:** P0 (Crítica) **Estimación:** 3-4 días **Versión:** 1.0 --- ## Historia de Usuario **Como** Director de Proyectos **Quiero** crear la estructura jerárquica completa de un fraccionamiento horizontal (Etapas → Manzanas → Lotes → Viviendas) **Para** organizar y controlar el desarrollo del proyecto con todos sus componentes físicos --- ## Contexto de Negocio Un fraccionamiento horizontal típico se estructura como: ``` Fraccionamiento Los Pinos ├── Etapa 1 │ ├── Manzana A (20 lotes) │ ├── Manzana B (22 lotes) │ └── Manzana C (18 lotes) ├── Etapa 2 │ ├── Manzana D (25 lotes) │ └── Manzana E (20 lotes) └── Etapa 3 └── ... ``` La creación debe ser: - **Rápida**: Wizard de 4 pasos - **Flexible**: Creación masiva de lotes - **Validada**: No permitir duplicados de códigos - **Eficiente**: Asignación de prototipos en masa --- ## Criterios de Aceptación ### ✅ AC1: Acceso al Wizard de Estructura **Dado** que soy Director/Admin **Y** tengo un proyecto tipo "Fraccionamiento Horizontal" **Cuando** accedo al detalle del proyecto **Entonces** debo ver botón "Crear Estructura" **Y** al hacer clic, se abre wizard de 4 pasos: 1. Crear Etapas 2. Crear Manzanas 3. Crear Lotes (en masa) 4. Resumen y Confirmación --- ### ✅ AC2: Paso 1 - Crear Etapas **Formulario por etapa:** - Código (auto-generado: ETAPA-1, ETAPA-2) - Nombre (ej: "Etapa 1 - Los Pinos Norte") - Área total (m²) - Fechas planificadas: inicio, fin - Número de manzanas estimadas **Validaciones:** - Código único dentro del proyecto - Área > 0 - Fecha fin >= Fecha inicio **Funcionalidad:** - Botón "+ Agregar Etapa" para crear múltiples - Mínimo 1 etapa obligatoria - Vista previa: "3 etapas, 185 lotes estimados" --- ### ✅ AC3: Paso 2 - Crear Manzanas por Etapa **Dado** que completé Paso 1 con 3 etapas **Entonces** en Paso 2 veo: ``` Etapa 1: [+ Agregar Manzana] - Manzana A: 20 lotes, 2,400 m² - Manzana B: 22 lotes, 2,640 m² Etapa 2: [+ Agregar Manzana] - Manzana C: 25 lotes, 3,000 m² ``` **Formulario por manzana:** - Código (sugerido: MZA-A, MZA-B, editable) - Nombre - Número de lotes - Área total (m²) - Infraestructura: ☑ Agua ☑ Drenaje ☑ Electricidad ☑ Alumbrado ☑ Pavimento **Funcionalidad:** - Asistente de códigos (A, B, C... Z, AA, AB...) - Calculadora: "20 lotes × 120m² = 2,400m² + 30% áreas verdes = 3,120m² total" - Mínimo 1 manzana por etapa --- ### ✅ AC4: Paso 3 - Crear Lotes en Masa **Dado** que completé Paso 2 con manzanas creadas **Entonces** en Paso 3 puedo crear lotes en masa por manzana: ``` Manzana A (20 lotes): [Creación Masiva] Cantidad: [20] Código prefijo: [LOTE-] Número inicial: [1] Dimensiones: - Área: [120] m² - Frente: [6] m - Fondo: [20] m - Forma: [Rectangular ▼] Se crearán: LOTE-001, LOTE-002, ... LOTE-020 [Crear Lotes] ``` **O** creación individual: - Botón "+ Agregar Lote Manual" - Para lotes con dimensiones especiales (esquina, irregular) **Validaciones:** - Máximo 500 lotes por operación - Códigos únicos dentro de la etapa - Área > 0 --- ### ✅ AC5: Paso 4 - Resumen y Confirmación **Muestra resumen completo:** ``` ┌────────────────────────────────────────────────────────┐ │ Resumen de Estructura │ ├────────────────────────────────────────────────────────┤ │ │ │ Total Etapas: 3 │ │ Total Manzanas: 8 │ │ Total Lotes: 185 │ │ Área Total: 67,200 m² │ │ │ │ Desglose por Etapa: │ │ │ │ Etapa 1 - Los Pinos Norte │ │ • 3 manzanas (A, B, C) │ │ • 62 lotes │ │ • 22,320 m² │ │ │ │ Etapa 2 - Los Pinos Centro │ │ • 3 manzanas (D, E, F) │ │ • 68 lotes │ │ • 24,480 m² │ │ │ │ Etapa 3 - Los Pinos Sur │ │ • 2 manzanas (G, H) │ │ • 55 lotes │ │ • 20,400 m² │ │ │ │ [← Regresar] [Crear Estructura →] │ └────────────────────────────────────────────────────────┘ ``` **Al confirmar:** - Transacción atómica (todo o nada) - Barra de progreso: "Creando estructura... 45%" - Al completar: "Estructura creada: 3 etapas, 8 manzanas, 185 lotes" - Redirige a vista de árbol jerárquico --- ### ✅ AC6: Vista de Árbol Jerárquico **Después de crear estructura, debo ver TreeView:** ``` ▼ 🏘️ Fraccionamiento Los Pinos │ ├─▼ 📂 Etapa 1 - Los Pinos Norte (planeada, 62 lotes) │ │ │ ├─▼ 🏗️ Manzana A (20 lotes, 0% infraestructura) │ │ ├─ 📦 LOTE-001 (120 m², disponible) │ │ ├─ 📦 LOTE-002 (120 m², disponible) │ │ └─ ... (18 más) │ │ │ ├─▼ 🏗️ Manzana B (22 lotes) │ │ └─ ... │ │ │ └─▼ 🏗️ Manzana C (20 lotes) │ └─ ... │ ├─▶ 📂 Etapa 2 (colapsada) │ └─▶ 📂 Etapa 3 (colapsada) ``` **Funcionalidades del árbol:** - Expandir/colapsar niveles - Filtros: por estado, por prototipo asignado - Búsqueda: por código de lote - Acciones rápidas: editar, eliminar, asignar prototipo - Exportar a Excel --- ### ✅ AC7: Edición de Estructura Existente **Dado** que ya existe estructura creada **Entonces** puedo: **Agregar elementos:** - "+ Nueva Etapa" (al proyecto) - "+ Nueva Manzana" (a una etapa) - "+ Nuevos Lotes" (a una manzana, en masa o individual) **Editar elementos:** - Cambiar nombre, código, dimensiones - Actualizar estado (planeada → en_proceso → terminada) - Marcar infraestructura completada **Eliminar elementos:** - Solo si NO tienen hijos (lote sin vivienda, manzana sin lotes) - Confirmación: "¿Eliminar Manzana A y sus 20 lotes?" --- ### ✅ AC8: Validaciones de Negocio **Códigos únicos:** - Etapa: único en proyecto - Manzana: único en etapa - Lote: único en etapa (puede repetirse en diferentes etapas) **Restricciones:** - No permitir eliminar etapa con lotes vendidos - No permitir eliminar manzana con lotes en construcción - Al eliminar manzana, eliminar cascada de lotes **Cálculos automáticos:** - `totalLots` en manzana = COUNT(lots) - `totalLots` en etapa = SUM(totalLots de manzanas) - `totalAreaSqm` = SUM(areaSqm de lotes) --- ## Escenarios de Prueba ### Escenario 1: Crear Estructura Completa (Happy Path) **Given** proyecto "Fraccionamiento Los Pinos" en estado Adjudicado **When** completo wizard con: - 3 etapas - 8 manzanas totales - 185 lotes creados en masa **Then** estructura se crea exitosamente **And** puedo ver árbol jerárquico completo **And** métricas del proyecto se actualizan: totalHousingUnits = 185 --- ### Escenario 2: Crear Lotes en Masa con Códigos Secuenciales **Given** Manzana A necesita 50 lotes **When** uso creación masiva: - Cantidad: 50 - Prefijo: LOTE- - Inicio: 1 **Then** sistema crea: LOTE-001, LOTE-002, ... LOTE-050 **And** todos con área 120 m² y forma rectangular --- ### Escenario 3: Validación de Código Duplicado **Given** ya existe lote LOTE-001 en Manzana A **When** intento crear otro LOTE-001 en la misma Manzana A **Then** sistema muestra error: "El código LOTE-001 ya existe en esta etapa" **And** no permite guardar --- ## Definición de Done (DoD) - [ ] Wizard de 4 pasos funcional - [ ] Creación masiva de lotes (hasta 500) - [ ] Validación de códigos únicos - [ ] TreeView con expandir/colapsar - [ ] Edición de elementos existentes - [ ] Eliminación con validación de dependencias - [ ] Transacción atómica (rollback si falla) - [ ] Tests de creación masiva - [ ] Performance: crear 500 lotes en <3 segundos - [ ] Responsive (mobile/tablet/desktop) --- ## Notas Técnicas **Endpoints:** ``` POST /api/projects/:projectId/stages POST /api/stages/:stageId/blocks POST /api/stages/:stageId/lots/bulk GET /api/projects/:projectId/structure/tree ``` **Bulk Creation:** ```typescript { "stageId": "uuid", "blockId": "uuid", "quantity": 50, "codePrefix": "LOTE-", "startNumber": 1, "areaSqm": 120, "frontMeters": 6, "depthMeters": 20, "shape": "rectangular" } ``` --- ## Dependencias **Depende de:** - ✅ US-PROJ-001: Catálogo de Proyectos - ✅ ET-PROJ-002: Especificación de estructura jerárquica **Bloquea a:** - US-PROJ-006: Asignación de Prototipos (necesita lotes) --- **Fecha:** 2025-11-17 **Estado:** ✅ Ready for Development