# MTC Assessments Plugin

Self-contained plugin for the assessment forms system. Handles clinical questionnaires that patients complete before purchasing prescription products — collecting medical history, screening contraindications, flagging answers for pharmacist review, and recommending/excluding products.

## Setup

After pulling this plugin for the first time, run these three steps:

```sh
# 1. Regenerate the autoloader (picks up the MtcPharmacy\Assessments namespace)
composer dump-autoload

# 2. Run migrations (updates the admin menu link to point to the plugin)
make migrate

# 3. Rebuild frontend assets (Vite entry points have changed)
npm run dev        # or npm run build for production
```

No `.env` changes are required — the plugin is enabled by default.

## Vite Configuration

The plugin requires the following entries in `vite.config.js`:

**Entry points** (in `build.rollupOptions.input`):
```js
assessments: resolve(__dirname, 'plugins/mtc_assessments/js/assessments.js'),
admin_form_builder: resolve(__dirname, 'plugins/mtc_assessments/admin/js/admin_form_builder.js'),
```

- `assessments` — public assessment form bundle (Vue app, Vuex store, all field components, LESS styles)
- `admin_form_builder` — admin visual builder bundle (separate Vue app, lives under `admin/js/` per the project's plugin convention)

**LESS variable injection** is path-conditional (in `css.preprocessorOptions.less.additionalData`):

- **Public LESS** (everything outside an `/admin/` segment) gets the public stack: `sites/default/css/variables.less` + `plugins/mtc_assessments/css/variables.less` + `core/css/mixins.less` + `sites/default/css/base/mixins.less`. The plugin's `css/variables.less` defines public-only custom properties like `--assessment_content_background`, `--assessment_dark_color`, `--assessment_step_color`.
- **Admin LESS** (any path containing `/admin/`, including every Vue SFC under `admin/js/`) gets a slim plugin-local pair: `plugins/mtc_assessments/admin/css/admin_variables.less` + `plugins/mtc_assessments/admin/css/admin_mixins.less`. Values mirror `core/admin/styleguide.php` (`--alert_color: #e74c3c`, `--success_color: #2ecc71`, `--information_color: #f1c40f`, `--primary_color: #0f55c4`, `@base_font_size: 13`).

Public and admin token sets are kept entirely separate so admin styling never affects the front end and the public theme never leaks into the admin builder.

## What This Plugin Provides

### Assessment Types

- **Form** — Standalone questionnaire at `/assessment/{form_id}`
- **Category** — Linked from a product category page, filters products after completion
- **Product** — Linked from a specific product page, pre-selects that product

### Admin

- **Form Management** — List, create, copy, delete assessment forms
- **Legacy Form Editor** — Table-based editor for form and question configuration
- **Visual Builder** — Vue-based drag-and-drop form builder with live preview
- **BMI/Ethnicity Management** — Configure BMI thresholds per ethnicity
- **Recommended Products** — Assign recommended/excluded products per answer variation

Admin pages are served at `/plugins/mtc_assessments/admin/assessment/`.

### Frontend

- Multi-step form with 13 field types (yes/no, variations, date, BMI calculator, image upload, GP search, etc.)
- Conditional visibility, blocker logic, and pharmacist review flags
- Product recommendations after form completion
- Vue 2 + Vuex store architecture

### API

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/admin/api/assessment/forms/{id}/builder` | Load form structure for builder |
| PATCH | `/admin/api/assessment/forms/{id}` | Rename form |
| POST | `/admin/api/assessment/questions` | Create question |
| PATCH | `/admin/api/assessment/questions/{id}` | Update question |
| DELETE | `/admin/api/assessment/questions/{id}` | Delete question |
| POST | `/admin/api/assessment/forms/{id}/reorder` | Reorder questions |
| GET | `/assessment/{form_id}` | Public assessment form |
| POST | `/assessment/{form_id}` | Submit assessment |

## Directory Structure

```
plugins/mtc_assessments/
├── loader.php                      # Auto-discovered by core, registers ServiceProvider
├── config/assessments.php          # Plugin configuration
├── src/
│   ├── AssessmentsServiceProvider.php  # Routes, migrations, config, class aliases
│   ├── Models/                     # Eloquent models (Form, Question, Assessment, Answer, etc.)
│   ├── Events/                     # AssessmentInitEvent, AssessmentCreatedEvent
│   ├── Http/Controllers/           # Builder, Display, Checkout controllers
│   ├── routes/web.php              # All assessment routes
│   └── templates/                  # Frontend Twig templates
├── admin/
│   ├── assessment/                 # Legacy admin PHP pages + builder.php
│   ├── templates/                  # Admin Twig templates
│   ├── orders/templates/           # Order assessment view templates
│   ├── js/
│   │   ├── admin_form_builder.js   # Vite entry point for the visual builder
│   │   └── components/
│   │       └── assessment_builder/ # Admin builder Vue components + Vuex store
│   └── css/
│       ├── admin_variables.less    # Plugin-local admin token set (mirrors styleguide)
│       └── admin_mixins.less       # Slim admin-only mixins (.rems() against base 13)
├── js/
│   ├── store/assessment_store.js   # Vuex store module (frontend form state)
│   └── components/
│       └── assessment/             # Frontend Vue components (form, fields, elements)
├── css/assessment.less             # Frontend assessment styles
└── database/
    ├── migrations/                 # Schema changes for assessment tables
    └── seeders/                    # Assessment data seeders
```

## Namespace

```
MtcPharmacy\Assessments\
├── Models\          (Form, Question, Assessment, Answer, AnswerMagento, AssessmentEthnicity, BmiEthnicity)
├── Events\          (AssessmentInitEvent, AssessmentCreatedEvent)
└── Http\Controllers\ (AssessmentBuilderController, AssessmentDisplayController, AssessmentCheckoutController)
```

### Backwards Compatibility

The `AssessmentsServiceProvider` registers class aliases so existing code using the old namespaces continues to work:

- `Mtc\Shop\Assessment\*` aliases to `MtcPharmacy\Assessments\Models\*`
- `App\Events\AssessmentInitEvent` aliases to `MtcPharmacy\Assessments\Events\AssessmentInitEvent`
- `App\Events\AssessmentCreatedEvent` aliases to `MtcPharmacy\Assessments\Events\AssessmentCreatedEvent`

These aliases allow the 50+ files across the codebase (Clinic, Subscriptions, QualifyingAnswers, Wisebee, Shop core, etc.) that reference assessment classes to work without modification.

## Vuex Store

The frontend assessment form uses a Vuex store module at `js/components/assessment/store/assessment_store.js`. This is registered as a non-namespaced module named `assessment` in the main store compositor at `sites/default/js/components/store/store.js`.

State is accessed via `$store.state.assessment.*` (sections, products, type, user, etc.). Dispatches use non-namespaced action names: `$store.dispatch('setAssessmentSection', ...)`.

## Events

Other plugins can listen to assessment lifecycle events:

- **`AssessmentInitEvent`** — Fired when a user opens an assessment form
- **`AssessmentCreatedEvent`** — Fired when a user submits a completed assessment

Currently consumed by: Clinic, Subscriptions, Wisebee.

## Configuration

`config/assessments.php`:

```php
return [
    'enabled' => env('ASSESSMENTS_ENABLED', true),
];
```