273 lines
18 KiB
Markdown
273 lines
18 KiB
Markdown
# Implementation Plan: Go No Go
|
|
|
|
Bare Laravel 12 + Nova 5 install to production-ready questionnaire application.
|
|
|
|
**Current state:** Laravel framework and Nova installed (Nova auth already working). No Inertia, Vue, Socialite, or application code.
|
|
|
|
**Reference docs:** `docs/technical-requirements.md`, `docs/theming-templating-vue.md`, `docs/questions-*.md`
|
|
|
|
---
|
|
|
|
## Step 1: Install Dependencies and Configure Build
|
|
|
|
[ ] **Install and configure the frontend toolchain and auth packages.**
|
|
|
|
Install Vue 3, Inertia.js v2 (server-side adapter + client-side `@inertiajs/vue3`), Tailwind CSS 4 with design tokens from `docs/theming-templating-vue.md`, Heroicons, and Laravel Socialite. Configure `vite.config.js` for Vue + Inertia. Configure `tailwind.config.js` with the project color tokens (primary `#d1ec51`, secondary `#00b7b3`, surface `#2b303a`). Register the `HandleInertiaRequests` middleware. Create the Inertia root Blade template (`app.blade.php`).
|
|
|
|
**Creates:**
|
|
- `vite.config.js` -- Vue plugin + Inertia page resolver
|
|
- `tailwind.config.js` -- custom color tokens
|
|
- `resources/views/app.blade.php` -- Inertia root template with `@vite` and `@inertiaHead`
|
|
- `resources/js/app.js` -- Vue + Inertia app bootstrap
|
|
- `app/Http/Middleware/HandleInertiaRequests.php`
|
|
- `composer.json` updates: `inertiajs/inertia-laravel`, `laravel/socialite`
|
|
- `package.json` updates: `vue`, `@inertiajs/vue3`, `@vitejs/plugin-vue`, `@heroicons/vue`, `tailwindcss`
|
|
|
|
**Validates:** `npm run build` completes without errors. Visiting any route renders the Inertia root template without a blank page or console errors.
|
|
|
|
---
|
|
|
|
## Step 2: Database -- Migrations and Models
|
|
|
|
[ ] **Create all database tables and Eloquent models.**
|
|
|
|
Create migrations for: `categories`, `question_groups`, `questions`, `screenings`, `screening_answers`, `sessions`, `answers`, `logs`. Create corresponding Eloquent models with relationships, `$fillable`, `$casts`, and any unique constraints (e.g., `answers` has a unique composite on `session_id + question_id`, `screening_answers` has a unique composite on `screening_id + question_number`). The `logs` table has no `updated_at` column (append-only). The `sessions` table has a nullable `screening_id` FK linking back to the screening that authorized it. See `docs/technical-requirements.md` section 5 for exact column definitions.
|
|
|
|
**Creates:**
|
|
- `database/migrations/*_create_categories_table.php`
|
|
- `database/migrations/*_create_question_groups_table.php`
|
|
- `database/migrations/*_create_questions_table.php`
|
|
- `database/migrations/*_create_screenings_table.php`
|
|
- `database/migrations/*_create_screening_answers_table.php`
|
|
- `database/migrations/*_create_sessions_table.php`
|
|
- `database/migrations/*_create_answers_table.php`
|
|
- `database/migrations/*_create_logs_table.php`
|
|
- `app/Models/Category.php`
|
|
- `app/Models/QuestionGroup.php`
|
|
- `app/Models/Question.php`
|
|
- `app/Models/Screening.php`
|
|
- `app/Models/ScreeningAnswer.php`
|
|
- `app/Models/Session.php`
|
|
- `app/Models/Answer.php`
|
|
- `app/Models/Log.php`
|
|
|
|
**Validates:** `herd php artisan migrate:fresh` runs cleanly. All models load without errors. `herd php artisan app:schema-generate` produces `database/schema.md` matching the spec.
|
|
|
|
---
|
|
|
|
## Step 3: Authentication
|
|
|
|
[ ] **Set up Socialite for frontend SSO.**
|
|
|
|
Nova already handles its own admin authentication at `/cp` (built-in). Configure Socialite with the Azure AD driver for frontend SSO. Create `SocialiteController` with `redirect`, `callback`, and `logout` methods. The callback creates or matches users by email. Add the `/login-jonathan` dev auto-login route (local/testing environments only).
|
|
|
|
**Creates:**
|
|
- `app/Http/Controllers/Auth/SocialiteController.php`
|
|
- `config/services.php` Azure AD configuration
|
|
- Route registrations in `routes/web.php` for `/login`, `/auth/callback`, `/logout`, `/login-jonathan`
|
|
|
|
**Validates:** Visiting `/login` redirects to Azure AD (or errors with missing credentials, confirming the redirect is wired). Nova login at `/cp` continues to work as before. `/login-jonathan` logs in and redirects to `/` in local environment.
|
|
|
|
---
|
|
|
|
## Step 4: Frontend Layout and Shared Components
|
|
|
|
[ ] **Build the persistent layout and all shared Vue components.**
|
|
|
|
Create `AppLayout.vue` as a persistent Inertia layout with `PageHeader` containing the Piccadilly logo and page title. Create shared components: `AppLogo`, `PageHeader`, `AppButton` (with variant/size/href/disabled/loading props per `docs/theming-templating-vue.md`), `ScoreIndicator` (color-coded by threshold). Wire up `HandleInertiaRequests` shared data (authenticated user, flash messages). Add the `EncryptHistory` middleware for sensitive session data.
|
|
|
|
**Creates:**
|
|
- `resources/js/Layouts/AppLayout.vue`
|
|
- `resources/js/Components/AppLogo.vue`
|
|
- `resources/js/Components/PageHeader.vue`
|
|
- `resources/js/Components/AppButton.vue`
|
|
- `resources/js/Components/ScoreIndicator.vue`
|
|
- Shared data configuration in `HandleInertiaRequests.php`
|
|
- `EncryptHistory` middleware registration
|
|
|
|
**Validates:** A test page using `AppLayout` renders the header with logo and title. `AppButton` renders all three variants. Shared data (`$page.props.auth.user`) is accessible in any page component.
|
|
|
|
---
|
|
|
|
## Step 5: Page Stubs and Click-Through Flow
|
|
|
|
[ ] **Create stub pages and controllers so the full two-stage navigation flow is clickable end to end.**
|
|
|
|
Create stub Vue page components for the entire flow: `Pages/Landing.vue` (intro text + Continue button), `Pages/Screening/Show.vue` (placeholder for pre-screening questions), `Pages/Screening/Result.vue` (placeholder pass/fail + category picker), `Pages/Session/Show.vue` (placeholder for basic info + questionnaire), `Pages/Session/Result.vue` (placeholder final result + Again button). Create stub controllers: `LandingController@index`, `ScreeningController` with `store`, `show`, `update`, `result` methods, `SessionController` with `store`, `show`, `update`, `result` methods. Wire up all routes in `web.php` matching the route table in `docs/technical-requirements.md` section 6.
|
|
|
|
This step is intentionally minimal -- no real data, no real forms. The goal is a complete clickable flow: Landing → Screening → Screening Result (with hardcoded category list) → Session/Show → Session/Result → back to Landing.
|
|
|
|
**Creates:**
|
|
- `resources/js/Pages/Landing.vue`
|
|
- `resources/js/Pages/Screening/Show.vue`
|
|
- `resources/js/Pages/Screening/Result.vue`
|
|
- `resources/js/Pages/Session/Show.vue`
|
|
- `resources/js/Pages/Session/Result.vue`
|
|
- `app/Http/Controllers/LandingController.php`
|
|
- `app/Http/Controllers/ScreeningController.php`
|
|
- `app/Http/Controllers/SessionController.php`
|
|
- All frontend route definitions in `routes/web.php`
|
|
|
|
**Validates:** Log in via `/login-jonathan`. See the landing page with Continue button. Click Continue to reach pre-screening. Click through to screening result. Select a category to start a session. Navigate through to the final result page. Click "Again" to return to landing. All page transitions work without errors. Browser back/forward works.
|
|
|
|
---
|
|
|
|
## Step 6: Seeders -- Categories, Question Groups, and Questions
|
|
|
|
[ ] **Seed all reference data: pre-screening questions, 6 categories, their question groups, and all questions with correct field configuration.**
|
|
|
|
Create `DatabaseSeeder` (or dedicated seeders) for: the 10 pre-screening Yes/No questions (stored in config or a seeder — these are not in the `questions` table, they are handled by the screening flow), the 6 categories (Audit, Outsource, Solution, Digital Solutions, Legal, Tax) with correct `sort_order`, all question groups per category with names, descriptions, and `scoring_instructions` where applicable, and all questions with the correct `has_yes`, `has_no`, `has_na`, `details`, `is_scored`, and `sort_order` values. Source question data from `docs/questions-audit.md`, `docs/questions-outsource-solutions.md`, `docs/questions-digital-solutions.md`, `docs/questions-legal.md`, `docs/questions-tax.md`.
|
|
|
|
**Creates:**
|
|
- `database/seeders/DatabaseSeeder.php`
|
|
- `database/seeders/CategorySeeder.php` (or inline)
|
|
- `database/seeders/QuestionSeeder.php` (or per-category seeders)
|
|
- Pre-screening question definitions (config file or seeder)
|
|
|
|
**Validates:** `herd php artisan migrate:fresh --seed` runs cleanly. Verify category count is 6. Verify each category has the expected number of question groups. Spot-check several questions to confirm field configuration matches the source docs. Verify 10 pre-screening questions are available.
|
|
|
|
---
|
|
|
|
## Step 7: Landing Page and Pre-Screening Flow
|
|
|
|
[ ] **Build the real landing page and pre-screening questionnaire.**
|
|
|
|
Build the Landing page: describes the application purpose (what Go/No Go is, what the user will do), with a "Continue" button that creates a screening and redirects to the pre-screening questions. Build the Screening/Show page: render the 10 Yes/No pre-screening questions using `useForm`. Save screening answers via `PUT /screening/{screening}`. On submit, calculate the screening score (Yes=1 point each), determine pass/fail (>=5 = pass), and redirect to the screening result page. Build Screening/Result: if failed (<5 points), show No Go result with "Again" button back to `/`. If passed, show the category picker (list of 6 categories) with "Start" buttons. Selecting a category creates a session linked to this screening and redirects to Session/Show.
|
|
|
|
**Creates:**
|
|
- Updated `resources/js/Pages/Landing.vue` -- application description + Continue button
|
|
- Updated `resources/js/Pages/Screening/Show.vue` -- 10 Yes/No questions with useForm
|
|
- Updated `resources/js/Pages/Screening/Result.vue` -- pass/fail display + category picker on pass
|
|
- Updated `app/Http/Controllers/LandingController.php`
|
|
- Updated `app/Http/Controllers/ScreeningController.php` -- full store/show/update/result logic
|
|
- Screening scoring logic
|
|
|
|
**Validates:** Landing page renders with description and Continue button. Clicking Continue creates a screening and shows 10 questions. Answering all No (score 0) → No Go result. Answering 5+ Yes → pass, category picker shown. Selecting a category creates a session and navigates to Session/Show.
|
|
|
|
---
|
|
|
|
## Step 8: Basic Info Form
|
|
|
|
[ ] **Build the basic info step as the first section of Session/Show.**
|
|
|
|
Add the basic info form fields to the Session/Show page: `client_name`, `client_contact`, `lead_firm_name`, `lead_firm_contact`. Use Inertia `useForm` to save data to the session's `basic_info` JSON column via `PUT /sessions/{session}`. All four fields are required before the user can proceed to questions. Display validation errors inline.
|
|
|
|
**Creates:**
|
|
- Updated `resources/js/Pages/Session/Show.vue` -- basic info form section
|
|
- Updated `app/Http/Controllers/SessionController.php` -- handle basic info save in `update` method
|
|
- Form validation rules for basic info fields
|
|
|
|
**Validates:** Starting a new session shows the basic info form. Submitting with empty fields shows validation errors. Filling all fields and saving persists to the `basic_info` JSON column. Refreshing the page retains the saved values.
|
|
|
|
---
|
|
|
|
## Step 9: Questionnaire Flow -- Question Rendering and Answer Saving
|
|
|
|
[ ] **Build the full questionnaire UI with all 6 question patterns and answer persistence.**
|
|
|
|
Create the `QuestionCard` component that renders questions based on their field configuration (see the 6 patterns in `docs/technical-requirements.md` section 5). Render question groups as steps within `Session/Show`. Each step shows its questions, scoring instructions (if present), and a "Next" / "Previous" navigation. Save answers via `PUT /sessions/{session}` using Inertia `useForm` with partial reloads (only reload answers/score, not the full question set). Handle `details` textarea visibility: show when `details` is `required` or `optional`; show conditionally for `req_on_yes` / `req_on_no` based on the selected value. Include the Additional Comments textarea as the final step.
|
|
|
|
**Creates:**
|
|
- `resources/js/Components/QuestionCard.vue`
|
|
- Updated `resources/js/Pages/Session/Show.vue` -- step navigation, question group rendering
|
|
- Updated `app/Http/Controllers/SessionController.php` -- answer saving logic in `update`
|
|
- Answer validation rules
|
|
|
|
**Validates:** Navigate through all question groups for a category. Each question renders the correct UI pattern (radio buttons, text-only, details visibility). Answers save without page reload. Navigating away and back retains saved answers. All 6 question patterns render correctly.
|
|
|
|
---
|
|
|
|
## Step 10: Scoring and Result
|
|
|
|
[ ] **Implement server-side scoring and the result page.**
|
|
|
|
Calculate the score server-side from `is_scored` answers: Yes=1, No=0, NA=excluded. Return the running score and current result threshold via Inertia props during the questionnaire. Build the `ScoreIndicator` into the questionnaire flow with live color updates (green 10+, yellow 5-9, red 1-4). Build the real `Session/Result` page showing the final GO / NO GO / Consult Leadership result with color coding and an "Again" button that returns to `/`. On session submission, calculate final score and persist `score`, `result`, `status=completed`, and `completed_at` to the session.
|
|
|
|
**Creates:**
|
|
- Scoring logic (service class or model method)
|
|
- Updated `app/Http/Controllers/SessionController.php` -- scoring in `update` (completion) and `result`
|
|
- Updated `resources/js/Pages/Session/Show.vue` -- ScoreIndicator integration
|
|
- Updated `resources/js/Pages/Session/Result.vue` -- final result display
|
|
- Updated `resources/js/Components/ScoreIndicator.vue` -- live threshold colors
|
|
|
|
**Validates:** Complete a session with known answers and verify the score matches manual calculation. ScoreIndicator changes color as answers are saved. Result page displays the correct GO/NO GO/Consult result. Session record in the database has correct `score`, `result`, and `completed_at`.
|
|
|
|
---
|
|
|
|
## Step 11: Activity Logging
|
|
|
|
[ ] **Add append-only activity logging for analytics.**
|
|
|
|
Create a logging service (or helper) that writes to the `logs` table. Integrate log writes into all relevant actions: `login`, `logout`, `screening_started`, `screening_completed`, `session_started`, `session_completed`, `session_abandoned`, `answer_saved`, `step_viewed`. Each log includes `user_id`, `session_id`, `category_id`, `action`, and `metadata` JSON as defined in `docs/technical-requirements.md` section 5 (logs table). The Log model should have no `updated_at` and should prevent updates/deletes.
|
|
|
|
**Creates:**
|
|
- `app/Services/ActivityLogger.php` (or similar)
|
|
- Log write calls in `SocialiteController`, `SessionController`, and relevant middleware/listeners
|
|
- Updated `app/Models/Log.php` -- guard against updates/deletes
|
|
|
|
**Validates:** Perform a full user flow (login, start session, answer questions, view steps, complete session, logout). Query the `logs` table and verify all expected actions are recorded with correct metadata.
|
|
|
|
---
|
|
|
|
## Step 12: Nova Resources and Policies
|
|
|
|
[ ] **Create all Nova resources, policies, and Excel export actions.**
|
|
|
|
Create Nova resources: `CategoryResource`, `QuestionGroupResource`, `QuestionResource`, `ScreeningResource`, `SessionResource`, `AnswerResource`, `LogResource`. Create corresponding policies enforcing the permission matrix from `docs/technical-requirements.md` section 9 (most are read-only; only Question.text is editable). Apply field behaviors: all fields filterable, sortable, and copyable where applicable. Set menu visibility (only Question, Screening, Session, Log appear in sidebar). Install `maatwebsite/laravel-nova-excel` and add `DownloadExcel` action to every resource.
|
|
|
|
**Creates:**
|
|
- `app/Nova/CategoryResource.php`
|
|
- `app/Nova/QuestionGroupResource.php`
|
|
- `app/Nova/QuestionResource.php`
|
|
- `app/Nova/ScreeningResource.php`
|
|
- `app/Nova/SessionResource.php`
|
|
- `app/Nova/AnswerResource.php`
|
|
- `app/Nova/LogResource.php`
|
|
- `app/Policies/CategoryPolicy.php`
|
|
- `app/Policies/QuestionGroupPolicy.php`
|
|
- `app/Policies/QuestionPolicy.php`
|
|
- `app/Policies/ScreeningPolicy.php`
|
|
- `app/Policies/SessionPolicy.php`
|
|
- `app/Policies/AnswerPolicy.php`
|
|
- `app/Policies/LogPolicy.php`
|
|
- Excel export action on all resources
|
|
|
|
**Validates:** Log in to Nova at `/cp`. QuestionResource, SessionResource, and LogResource appear in the sidebar. CategoryResource, QuestionGroupResource, and AnswerResource do not appear in the sidebar but are accessible via relational fields. Only Question.text is editable. Export to Excel works on each resource index. Attempting create/update/delete on read-only resources is denied.
|
|
|
|
---
|
|
|
|
## Step 13: Testing
|
|
|
|
[ ] **Write automated tests for critical paths.**
|
|
|
|
Write PHPUnit feature tests for: pre-screening scoring (pass/fail at 5-point threshold), category questionnaire scoring (known inputs produce expected scores), session lifecycle (create, answer, complete, abandon), answer saving and validation, policy authorization (CRUD permissions per resource), Socialite auth flow (mock Azure AD callback). Write Cypress E2E tests for: full two-stage flow (landing → screening → category selection → questionnaire → result → again), pre-screening fail path (score <5 → No Go), scoring display updates during questionnaire, result page shows correct outcome.
|
|
|
|
**Creates:**
|
|
- `tests/Feature/ScreeningScoringTest.php`
|
|
- `tests/Feature/ScoringTest.php`
|
|
- `tests/Feature/SessionLifecycleTest.php`
|
|
- `tests/Feature/AnswerTest.php`
|
|
- `tests/Feature/PolicyTest.php`
|
|
- `tests/Feature/AuthTest.php`
|
|
- `tests/cypress/e2e/questionnaire-flow.cy.js`
|
|
- `tests/cypress/e2e/scoring-display.cy.js`
|
|
- `tests/cypress/e2e/result-page.cy.js`
|
|
|
|
**Validates:** `herd php artisan test` passes all PHPUnit tests. `npx cypress run` passes all E2E tests. No regressions in existing functionality.
|
|
|
|
---
|
|
|
|
## Step 14: Production Readiness
|
|
|
|
[ ] **Final hardening, configuration, and review.**
|
|
|
|
Update `.env.example` with all required environment variables (Azure AD credentials, database, app URL, Nova license key). Create custom error pages (404, 500) using the app design system. Review eager loading across all controllers to prevent N+1 queries. Verify CSRF protection on all POST/PUT routes. Confirm `EncryptHistory` middleware is active on session routes. Run a full smoke test of the complete flow: SSO login, landing page, pre-screening (pass and fail paths), category selection, basic info, complete all questions, view result, click Again, check Nova admin, verify logs, export Excel.
|
|
|
|
**Creates:**
|
|
- Updated `.env.example`
|
|
- `resources/js/Pages/Error.vue` (or 404/500 specific pages)
|
|
- Query optimization passes on controllers
|
|
- Security checklist verification
|
|
|
|
**Validates:** Fresh clone + `composer install` + `npm install` + `herd php artisan migrate:fresh --seed` + `npm run build` produces a working application. Full user flow works end to end. Nova admin flow works. No console errors, no N+1 queries, no missing environment variables.
|