adds more documentation

2026-02-03 09:19:17 +01:00
parent 02dfc1568c
commit d38001e3e2
1 changed files with 287 additions and 0 deletions
--- a/docs/implementation-plan.md
+++ b/docs/implementation-plan.md
@@ -25,6 +25,13 @@ ## Step 1: Install Dependencies and Configure Build
 **Validates:** `npm run build` completes without errors. Visiting any route renders the Inertia root template without a blank page or console errors.
 **Browser Verification (Playwright MCP):**
 1. `browser_navigate` to `http://go-no-go.test`
 2. `browser_snapshot` -- confirm the page renders content (not a blank page or Vite error screen)
 3. `browser_console_messages` with level `error` -- verify no JavaScript console errors
 4. `browser_take_screenshot` -- save as `step-01-homepage.png` for visual confirmation
 5. If a default Laravel welcome or Inertia root page loads, the step passes
 ---
 ## Step 2: Database -- Migrations and Models
@@ -53,6 +60,12 @@ ## Step 2: Database -- Migrations and Models
 **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.
 **Browser Verification (Playwright MCP):**
 1. `browser_navigate` to `http://go-no-go.test`
 2. `browser_snapshot` -- confirm the app still loads without database connection errors or migration failures
 3. `browser_console_messages` with level `error` -- verify no errors
 4. No UI to test yet; this step is purely backend. Passing means the app does not crash after migrations.
 ---
 ## Step 3: Authentication
@@ -68,6 +81,15 @@ ## Step 3: Authentication
 **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.
 **Browser Verification (Playwright MCP):**
 1. `browser_navigate` to `http://go-no-go.test/login-jonathan`
 2. `browser_snapshot` -- confirm redirect to `/` after auto-login (page should show authenticated state)
 3. `browser_take_screenshot` -- save as `step-03-login-jonathan.png`
 4. `browser_navigate` to `http://go-no-go.test/cp`
 5. `browser_snapshot` -- confirm Nova login page loads (should show email/password form)
 6. `browser_take_screenshot` -- save as `step-03-nova-login.png`
 7. `browser_console_messages` with level `error` -- verify no errors on either page
 ---
 ## Step 4: Frontend Layout and Shared Components
@@ -87,6 +109,14 @@ ## Step 4: Frontend Layout and Shared Components
 **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.
 **Browser Verification (Playwright MCP):**
 1. `browser_navigate` to `http://go-no-go.test/login-jonathan` (authenticate first)
 2. `browser_navigate` to `http://go-no-go.test/` (or any test page using AppLayout)
 3. `browser_snapshot` -- confirm the layout renders: look for the Piccadilly logo in the header and the page title
 4. `browser_take_screenshot` -- save as `step-04-layout.png` to visually verify header, logo, and overall layout structure
 5. Verify the snapshot contains recognizable layout elements (header, logo component, page content area)
 6. `browser_console_messages` with level `error` -- verify no Vue rendering errors
 ---
 ## Step 5: Page Stubs and Click-Through Flow
@@ -110,6 +140,27 @@ ## Step 5: Page Stubs and Click-Through Flow
 **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.
 **Browser Verification (Playwright MCP):**
 1. `browser_navigate` to `http://go-no-go.test/login-jonathan` -- authenticate
 2. `browser_snapshot` -- confirm landing page with Continue button
 3. `browser_take_screenshot` -- save as `step-05-landing.png`
 4. `browser_click` the Continue button
 5. `browser_snapshot` -- confirm screening page loads (pre-screening stub)
 6. `browser_take_screenshot` -- save as `step-05-screening.png`
 7. Click through to the screening result page (click submit/continue on the screening stub)
 8. `browser_snapshot` -- confirm screening result page with category list
 9. `browser_take_screenshot` -- save as `step-05-screening-result.png`
 10. `browser_click` a category "Start" button to begin a session
 11. `browser_snapshot` -- confirm session/show page loads
 12. `browser_take_screenshot` -- save as `step-05-session-show.png`
 13. Click through to the session result page
 14. `browser_snapshot` -- confirm result page with "Again" button
 15. `browser_take_screenshot` -- save as `step-05-session-result.png`
 16. `browser_click` the "Again" button
 17. `browser_snapshot` -- confirm return to the landing page
 18. `browser_navigate_back` -- verify browser back navigation works without errors
 19. `browser_console_messages` with level `error` -- verify no errors throughout the entire flow
 ---
 ## Step 6: Seeders -- Categories, Question Groups, and Questions
@@ -126,6 +177,16 @@ ## Step 6: Seeders -- Categories, Question Groups, and Questions
 **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.
 **Browser Verification (Playwright MCP):**
 1. After running `herd php artisan migrate:fresh --seed`, `browser_navigate` to `http://go-no-go.test/login-jonathan`
 2. Navigate through the stub flow to verify seeded data appears:
   - `browser_navigate` to the screening result page -- verify the 6 category names appear (Audit, Outsource, Solution, Digital Solutions, Legal, Tax)
   - `browser_take_screenshot` -- save as `step-06-categories.png`
 3. Start a session for any category, navigate to the screening page -- verify seeded pre-screening questions render
 4. `browser_take_screenshot` -- save as `step-06-screening-questions.png`
 5. `browser_snapshot` -- confirm question text is present and not placeholder content
 6. `browser_console_messages` with level `error` -- verify no errors
 ---
 ## Step 7: Landing Page and Pre-Screening Flow
@@ -144,6 +205,33 @@ ## Step 7: Landing Page and Pre-Screening Flow
 **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.
 **Browser Verification (Playwright MCP):**
 *Test path 1 -- No Go (all No answers):*
 1. `browser_navigate` to `http://go-no-go.test/login-jonathan`
 2. `browser_snapshot` -- confirm landing page with description text and Continue button
 3. `browser_take_screenshot` -- save as `step-07-landing.png`
 4. `browser_click` the Continue button
 5. `browser_snapshot` -- confirm 10 pre-screening Yes/No questions render
 6. `browser_take_screenshot` -- save as `step-07-screening-questions.png`
 7. `browser_fill_form` -- select "No" for all 10 questions
 8. `browser_click` the Submit button
 9. `browser_snapshot` -- confirm No Go result page (score <5)
 10. `browser_take_screenshot` -- save as `step-07-nogo-result.png`
 11. Verify the page shows a No Go message and an "Again" button (no category picker)
 *Test path 2 -- Pass (5+ Yes answers):*
 12. `browser_navigate` to `http://go-no-go.test/` -- start fresh
 13. `browser_click` the Continue button
 14. `browser_fill_form` -- select "Yes" for at least 5 questions (e.g., first 6 Yes, rest No)
 15. `browser_click` the Submit button
 16. `browser_snapshot` -- confirm pass result with category picker showing 6 categories
 17. `browser_take_screenshot` -- save as `step-07-pass-result.png`
 18. `browser_click` a category "Start" button
 19. `browser_snapshot` -- confirm redirect to Session/Show page
 20. `browser_take_screenshot` -- save as `step-07-session-started.png`
 21. `browser_console_messages` with level `error` -- verify no errors across both paths
 ---
 ## Step 8: Basic Info Form
@@ -159,6 +247,33 @@ ## Step 8: Basic Info Form
 **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.
 **Browser Verification (Playwright MCP):**
 1. `browser_navigate` to `http://go-no-go.test/login-jonathan`
 2. Complete the pre-screening flow (5+ Yes) and select a category to start a session
 3. `browser_snapshot` -- confirm basic info form renders with 4 fields (client_name, client_contact, lead_firm_name, lead_firm_contact)
 4. `browser_take_screenshot` -- save as `step-08-basic-info-empty.png`
 *Test validation errors:*
 5. `browser_click` the Save/Submit button without filling any fields
 6. `browser_snapshot` -- confirm validation error messages appear for all 4 required fields
 7. `browser_take_screenshot` -- save as `step-08-validation-errors.png`
 *Test successful submission:*
 8. `browser_fill_form` -- fill all 4 fields with test data:
   - client_name: "Test Client Ltd"
   - client_contact: "Jane Doe"
   - lead_firm_name: "Lead Firm BV"
   - lead_firm_contact: "John Smith"
 9. `browser_click` the Save button
 10. `browser_snapshot` -- confirm save succeeded (no validation errors)
 11. `browser_take_screenshot` -- save as `step-08-basic-info-filled.png`
 *Test persistence:*
 12. `browser_navigate` to the same session URL (refresh the page)
 13. `browser_snapshot` -- confirm all 4 fields still contain the previously saved values
 14. `browser_take_screenshot` -- save as `step-08-basic-info-retained.png`
 15. `browser_console_messages` with level `error` -- verify no errors
 ---
 ## Step 9: Questionnaire Flow -- Question Rendering and Answer Saving
@@ -175,6 +290,36 @@ ## Step 9: Questionnaire Flow -- Question Rendering and Answer Saving
 **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.
 **Browser Verification (Playwright MCP):**
 1. `browser_navigate` to `http://go-no-go.test/login-jonathan`
 2. Complete pre-screening (5+ Yes), select a category known to have diverse question types (e.g., Audit), fill basic info
 *Test question group navigation:*
 3. `browser_snapshot` -- confirm first question group renders with questions and Next button
 4. `browser_take_screenshot` -- save as `step-09-question-group-1.png`
 *Test all 6 question patterns (navigate through groups to find each):*
 5. For each question pattern encountered:
   - `browser_snapshot` -- verify correct UI elements (radio buttons for Yes/No/NA, details textarea visibility)
   - `browser_take_screenshot` -- save as `step-09-pattern-{N}.png` for each distinct pattern
 6. Verify details field behavior:
   - Find a question with `details: req_on_yes` -- select Yes, confirm details textarea appears
   - Select No on the same question -- confirm details textarea hides
   - `browser_take_screenshot` -- save as `step-09-conditional-details.png`
 *Test answer saving:*
 7. `browser_fill_form` -- answer several questions in the current group
 8. `browser_click` the Next button to go to the next group
 9. `browser_click` the Previous button to return
 10. `browser_snapshot` -- confirm previously saved answers are still selected
 11. `browser_take_screenshot` -- save as `step-09-answers-retained.png`
 *Test step navigation:*
 12. `browser_click` Next through all question groups to reach the Additional Comments step
 13. `browser_snapshot` -- confirm Additional Comments textarea renders
 14. `browser_take_screenshot` -- save as `step-09-additional-comments.png`
 15. `browser_console_messages` with level `error` -- verify no errors throughout navigation
 ---
 ## Step 10: Scoring and Result
@@ -192,6 +337,32 @@ ## Step 10: Scoring and Result
 **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`.
 **Browser Verification (Playwright MCP):**
 1. `browser_navigate` to `http://go-no-go.test/login-jonathan`
 2. Complete pre-screening, select a category, fill basic info
 *Test ScoreIndicator live updates:*
 3. Answer the first few scored questions with "Yes" (score builds up)
 4. `browser_snapshot` -- confirm ScoreIndicator is visible and shows current score
 5. `browser_take_screenshot` -- save as `step-10-score-low.png` (should be red, score 1-4)
 6. Continue answering "Yes" to build score to 5-9 range
 7. `browser_take_screenshot` -- save as `step-10-score-mid.png` (should be yellow)
 8. Continue answering "Yes" to push score above 10
 9. `browser_take_screenshot` -- save as `step-10-score-high.png` (should be green)
 *Test session submission and result:*
 10. Complete all remaining questions and navigate to the final step
 11. `browser_click` the Submit/Complete button
 12. `browser_snapshot` -- confirm result page loads with GO / NO GO / Consult Leadership verdict
 13. `browser_take_screenshot` -- save as `step-10-result-page.png`
 14. Verify the result page shows:
    - The correct result text (GO, NO GO, or Consult Leadership) based on the score
    - Appropriate color coding matching the result
    - An "Again" button
 15. `browser_click` the "Again" button
 16. `browser_snapshot` -- confirm return to the landing page
 17. `browser_console_messages` with level `error` -- verify no errors
 ---
 ## Step 11: Activity Logging
@@ -207,6 +378,28 @@ ## Step 11: Activity Logging
 **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.
 **Browser Verification (Playwright MCP):**
 *Step 1 -- Perform a full flow to generate log entries:*
 1. `browser_navigate` to `http://go-no-go.test/login-jonathan` -- triggers `login` log
 2. Complete pre-screening (triggers `screening_started`, `screening_completed`)
 3. Select a category and start a session (triggers `session_started`)
 4. Answer several questions (triggers `answer_saved`, `step_viewed`)
 5. Complete the session (triggers `session_completed`)
 *Step 2 -- Verify logs in Nova admin:*
 6. `browser_navigate` to `http://go-no-go.test/cp`
 7. `browser_fill_form` -- log in with Nova admin credentials (email: jonathan@blijnder.nl, password: secret)
 8. `browser_snapshot` -- confirm Nova dashboard loads
 9. `browser_click` the "Logs" item in the Nova sidebar
 10. `browser_snapshot` -- confirm log entries are listed with action types, user IDs, and timestamps
 11. `browser_take_screenshot` -- save as `step-11-nova-logs-index.png`
 12. `browser_click` a specific log entry to view its detail
 13. `browser_snapshot` -- confirm log detail shows action, user_id, session_id, category_id, and metadata JSON
 14. `browser_take_screenshot` -- save as `step-11-nova-log-detail.png`
 15. Verify that log entries include: `login`, `screening_started`, `screening_completed`, `session_started`, `answer_saved`, `step_viewed`, `session_completed`
 16. `browser_console_messages` with level `error` -- verify no errors
 ---
 ## Step 12: Nova Resources and Policies
@@ -234,6 +427,47 @@ ## Step 12: Nova Resources and Policies
 **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.
 **Browser Verification (Playwright MCP):**
 *Verify sidebar and navigation:*
 1. `browser_navigate` to `http://go-no-go.test/cp`
 2. `browser_fill_form` -- log in with Nova credentials (email: jonathan@blijnder.nl, password: secret)
 3. `browser_snapshot` -- confirm Nova dashboard loads, check sidebar items
 4. `browser_take_screenshot` -- save as `step-12-nova-sidebar.png`
 5. Verify sidebar contains: Questions, Screenings, Sessions, Logs
 6. Verify sidebar does NOT contain: Categories, Question Groups, Answers
 *Verify each resource index:*
 7. `browser_click` "Questions" in the sidebar
 8. `browser_snapshot` -- confirm question list loads with data
 9. `browser_take_screenshot` -- save as `step-12-nova-questions-index.png`
 10. `browser_click` "Sessions" in the sidebar
 11. `browser_take_screenshot` -- save as `step-12-nova-sessions-index.png`
 12. `browser_click` "Logs" in the sidebar
 13. `browser_take_screenshot` -- save as `step-12-nova-logs-index.png`
 *Verify read-only enforcement:*
 14. `browser_click` "Sessions" in the sidebar
 15. `browser_click` on a session row to view its detail
 16. `browser_snapshot` -- confirm detail view loads but no Edit or Delete buttons are present
 17. `browser_take_screenshot` -- save as `step-12-nova-session-detail-readonly.png`
 *Verify Question.text is editable:*
 18. `browser_click` "Questions" in the sidebar
 19. `browser_click` on a question row to view its detail
 20. `browser_snapshot` -- confirm an Edit button IS present for Questions
 21. `browser_click` the Edit button
 22. `browser_snapshot` -- confirm only the `text` field is editable; other fields are read-only or hidden
 23. `browser_take_screenshot` -- save as `step-12-nova-question-edit.png`
 *Verify Excel export:*
 24. `browser_click` "Questions" in the sidebar
 25. Select all items (checkbox), look for the Excel export action in the action dropdown
 26. `browser_snapshot` -- confirm "Download Excel" action is available
 27. `browser_take_screenshot` -- save as `step-12-nova-excel-export.png`
 28. `browser_console_messages` with level `error` -- verify no errors
 ---
 ## Step 13: Testing
@@ -255,6 +489,13 @@ ## Step 13: Testing
 **Validates:** `herd php artisan test` passes all PHPUnit tests. `npx cypress run` passes all E2E tests. No regressions in existing functionality.
 **Browser Verification (Playwright MCP):**
 No detailed browser verification needed for this step (automated tests handle validation). Perform a quick smoke test:
 1. `browser_navigate` to `http://go-no-go.test/login-jonathan`
 2. Complete a full end-to-end flow: landing -> pre-screening (pass) -> select category -> basic info -> answer questions -> submit -> result page -> click Again
 3. `browser_take_screenshot` at the result page -- save as `step-13-smoke-test-result.png`
 4. `browser_console_messages` with level `error` -- confirm no regressions introduced by test setup
 ---
 ## Step 14: Production Readiness
@@ -270,3 +511,49 @@ ## Step 14: Production Readiness
 - 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.
 **Browser Verification (Playwright MCP):**
 Full end-to-end smoke test covering every major screen:
 *Frontend flow:*
 1. `browser_navigate` to `http://go-no-go.test/login-jonathan`
 2. `browser_snapshot` -- confirm landing page
 3. `browser_take_screenshot` -- save as `step-14-e2e-landing.png`
 4. `browser_click` the Continue button
 5. `browser_fill_form` -- answer pre-screening questions (5+ Yes for pass path)
 6. `browser_click` Submit
 7. `browser_snapshot` -- confirm pass result with category picker
 8. `browser_take_screenshot` -- save as `step-14-e2e-screening-result.png`
 9. `browser_click` a category Start button
 10. `browser_fill_form` -- fill all 4 basic info fields
 11. `browser_click` Save
 12. `browser_take_screenshot` -- save as `step-14-e2e-basic-info.png`
 13. Navigate through all question groups, answering questions in each:
    - `browser_fill_form` for each group's questions
    - `browser_click` Next
    - `browser_take_screenshot` at representative groups -- save as `step-14-e2e-questions-{N}.png`
 14. Verify `ScoreIndicator` is visible and color-coded
 15. `browser_click` Submit/Complete on the final step
 16. `browser_snapshot` -- confirm result page with GO/NO GO/Consult verdict
 17. `browser_take_screenshot` -- save as `step-14-e2e-result.png`
 18. `browser_click` the "Again" button
 19. `browser_snapshot` -- confirm return to landing page
 *Nova admin flow:*
 20. `browser_navigate` to `http://go-no-go.test/cp`
 21. `browser_fill_form` -- log in (email: jonathan@blijnder.nl, password: secret)
 22. `browser_snapshot` -- confirm Nova dashboard
 23. `browser_take_screenshot` -- save as `step-14-e2e-nova-dashboard.png`
 24. `browser_click` "Sessions" in sidebar -- verify the just-completed session appears
 25. `browser_take_screenshot` -- save as `step-14-e2e-nova-sessions.png`
 26. `browser_click` "Logs" in sidebar -- verify log entries for the full flow
 27. `browser_take_screenshot` -- save as `step-14-e2e-nova-logs.png`
 *Error pages:*
 28. `browser_navigate` to `http://go-no-go.test/nonexistent-page`
 29. `browser_snapshot` -- confirm custom 404 page renders with app design system
 30. `browser_take_screenshot` -- save as `step-14-e2e-404.png`
 *Final check:*
 31. `browser_console_messages` with level `error` -- verify zero console errors across the entire flow
 32. `browser_network_requests` -- spot-check for any failed requests (non-2xx/3xx status codes)