GSB-Construction/PLAN-contractor-admin.md

Overview

This plan implements "Option A" for bootstrapping a Contractor Admin during Contractor creation. We will add specific fields to the Create.tsx frontend form and update the backend ContractorController@store method to provision the Contractor and their Admin user together in a single database transaction.

Project Type

WEB

Success Criteria

• The "Create Contractor" page includes fields for "Admin Credentials" (Name, Email, Password).
• Submitting the form creates BOTH a Contractor record and a User record.
• The new User is correctly tagged with the newly created contractor_id.
• The new User is assigned the contractor-admin role.
• If user creation fails, the Contractor is not created (safe rollback via DB transaction).

Tech Stack

• Frontend: React / Inertia.js (TypeScript)
• Backend: Laravel (PHP)
• Database: MySQL (DB Facade for transactions)

File Structure

Files to modify:

• Modules/ContractorManagement/resources/js/Pages/Contractors/Create.tsx
• Modules/ContractorManagement/app/Http/Controllers/ContractorController.php

Task Breakdown

Task 1: Update Frontend Contractor Creation Form

• Agent: frontend-specialist
• Skill: frontend-design, react-best-practices
• Action: Add an optional section for Admin User creation in Modules/ContractorManagement/resources/js/Pages/Contractors/Create.tsx.
• INPUT: Existing Create.tsx form.
• OUTPUT: Updated form with a section (e.g., "Provision Admin Account") that collects admin_name, admin_email, and admin_password. These fields are appended to the Inertia useForm hook.
• VERIFY: The form correctly sends admin_name, admin_email, and admin_password in the POST payload.

Task 2: Update Backend Controller to Handle User Provisioning

• Agent: backend-specialist
• Skill: api-patterns
• Action: Update the store() method in Modules/ContractorManagement/app/Http/Controllers/ContractorController.php.
• INPUT: ContractorController.php code.
• OUTPUT:
  • Validate admin_name, admin_email, and admin_password (if provided).
  • Wrap the database operations in DB::transaction().
  • Create the Contractor model.
  • If admin credentials were provided, create a User model with user_type set appropriately, contractor_id mapped to the new contractor, and password hashed.
  • Assign the contractor-admin role to the newly created User.
  • Set must_change_password to true (optional but recommended).
• VERIFY: Manual test that submitting the form successfully inserts both the Contractor and User records, and correctly assigns the role.

✅ PHASE X COMPLETE

• Lint: [x] Passed
• Security: [x] Code reviewed
• Build: [x] TSC Passed
• Date: