GSB-Construction/project-creation-wizard.md

Multi-Phase Project Creation Wizard — Implementation Plan

This plan transforms the current single-step project creation form into a guided, multi-phase wizard. The wizard allows users to sequentially define details, schedule tasks, list material requirements, allocate manpower and machinery costs, view financial estimations, submit for approval, and initiate requisitions/purchase orders.

User Review Required

We have outlined 3 strategic decisions for review:

1. Wizard State Persistence: Projects will be saved to the database immediately after Step 1 in a planning status with a current_wizard_step field. This enables users to leave the wizard and click "Resume Setup" later from the Project list.
2. Batch Persistence Endpoints: We will add batch store endpoints (wizard/tasks, wizard/estimates, etc.) to support seamless saving of multiple tasks, materials, or resource assignments at each step.
3. Approval Lifecycle Integration: When estimation is completed (Step 7), the project status transitions to a locked state, initiating a workflow via the ApprovalService (requiring project PM and management reviews) before procurement is unlocked.

---

Proposed Changes

Component 1: Database Schema

[NEW] 2026_05_28_100006_add_current_wizard_step_to_projects_table.php

• Add current_wizard_step (tinyint, default: 1) to track the user's progress through the project setup phases.

---

Component 2: Backend Routes & Controllers

[MODIFY] web.php

• Add wizard endpoints under /projects:
  • GET /projects/{project}/wizard -> Renders Projects/Wizard page.
  • POST /projects/{project}/wizard/tasks -> Save/update tasks & milestones.
  • POST /projects/{project}/wizard/estimates -> Save material estimates.
  • POST /projects/{project}/wizard/labor -> Save task labor hours.
  • POST /projects/{project}/wizard/equipment -> Save task equipment hours.
  • POST /projects/{project}/wizard/submit -> Submit project estimation for approval.

[MODIFY] ProjectController.php

• Modify store to redirect to /projects/{project}/wizard?step=2.
• Implement wizard step endpoints:
  • Return props for each step: standard materials lists, master rates, existing milestones, tasks, and labor/equipment data.
  • Implement batch transaction controllers for saving step-specific entities.

---

Component 3: Frontend wizard UI

[NEW] Wizard.tsx

• Guided wizard page with stepper header: Details -> Tasks -> Materials -> Manpower -> Equipment -> Estimation -> Submit
• Forms for each phase:
  • Details: Reuse fields from ProjectForm.tsx (Name, client, dates, unprofitable, parent).
  • Tasks: Form to add/edit milestones and tasks under them.
  • Materials: Reuses MaterialCatalogModal for multi-selection of estimated materials.
  • Manpower: Forms to assign labor trades & hours to scheduled tasks.
  • Equipment: Forms to assign equipment & hours to scheduled tasks.
  • Estimation: Rollup review dashboard (contract value, material/labor/machinery estimations, profit margin, unprofitable highlights).
  • Submit: Triggers validation and submits to ApprovalService.
  • MR & PO: Triggers routes to generate requisitions prefilled with estimated materials.

---

Decisions Made

• Estimation Lock-in: Once approved, estimates are locked down completely. Any adjustments will strictly require a Variation Order (extension project).
• Default Milestone Seeding: In Step 2, we will provide a toggle/checkbox (e.g., "Pre-populate Default Milestones") to let users choose whether to start with standard milestones or from scratch.
• Drafts Visibility: Incomplete projects (where current_wizard_step < 7) will be filtered out from the main projects table and displayed in a separate, dedicated "Draft Projects" tab.
• Tasks Module Integration: Tasks created in Step 2 of the wizard will be saved immediately to the database, ensuring they are instantly selectable and visible within the Tasks module (TaskManagement) when the project is queried.

---

Verification Plan

Automated Tests

• Create Modules/ProjectManagement/tests/Feature/ProjectWizardTest.php:
  • Verify project starts at step 1 and step increments on data submission.
  • Verify tasks, estimates, and resource rates are persisted under correct parent relations.
  • Verify submit transitions status and blocks MR/PO actions until approval is completed.

Manual Verification

• Walk through the wizard step-by-step, verify back/next actions preserve state in database.
• Navigate away on Step 3, return to Project, click "Resume Setup", and verify it redirects to Step 3.