# Feature: Policies

## Overview
The studio admin drafts, versions, and publishes policies (e.g. cancellation, payment, code of conduct). Registrants must read and accept the current published version of every policy before they can book. Acceptance is recorded against the specific version, so when a policy is updated students must re-accept it at their next booking.

## Data Model — `{prefix}us_policies`

| Column               | Type             | Notes                                          |
|----------------------|------------------|------------------------------------------------|
| `id`                 | BIGINT UNSIGNED  | Primary key                                    |
| `title`              | VARCHAR(191)     | Display name                                   |
| `slug`               | VARCHAR(191)     | Unique key, e.g. `cancellation`                |
| `current_version_id` | BIGINT UNSIGNED  | Nullable FK → `us_policy_versions.id` (published) |
| `acceptance_scope`   | VARCHAR(20)      | `signup` / `booking` / `both` — when it must be accepted |
| `created_at`         | DATETIME         | Insertion time                                 |

## Data Model — `{prefix}us_policy_versions`

| Column           | Type             | Notes                                              |
|------------------|------------------|----------------------------------------------------|
| `id`             | BIGINT UNSIGNED  | Primary key                                        |
| `policy_id`      | BIGINT UNSIGNED  | FK → `us_policies.id`                               |
| `version_number` | INT              | Increments per policy, starting at 1               |
| `body`           | LONGTEXT         | The policy text (HTML/markdown)                    |
| `status`         | VARCHAR(20)      | `draft` / `published` / `archived`                 |
| `published_at`   | DATETIME         | When published; NULL for drafts                    |
| `created_at`     | DATETIME         | Insertion time                                     |

## Data Model — `{prefix}us_policy_acceptances`

| Column              | Type             | Notes                                                  |
|---------------------|------------------|--------------------------------------------------------|
| `id`                | BIGINT UNSIGNED  | Primary key                                            |
| `policy_version_id` | BIGINT UNSIGNED  | FK → `us_policy_versions.id` (the exact version accepted) |
| `student_id`        | BIGINT UNSIGNED  | WordPress user ID                                     |
| `registration_type` | VARCHAR(20)      | `lesson` or `enrollment`                              |
| `registration_id`   | BIGINT UNSIGNED  | FK → `us_lessons.id` or `us_group_enrollments.id`     |
| `accepted_at`       | DATETIME         | Timestamp of acceptance                              |
| `ip_address`        | VARCHAR(45)      | IP captured at acceptance (audit trail)              |

## Versioning & Acceptance Rules
- Editing a published policy creates a new `draft` version; the old version stays `published` until the draft is published.
- Publishing a draft sets it `published`, stamps `published_at`, archives the prior version, and points `us_policies.current_version_id` at it.
- The registration gate requires acceptance of the `current_version_id` of every policy. Because acceptance is tied to `policy_version_id`, a newly published version is unaccepted and must be re-accepted at the student's next booking.

## Admin Interface
**Policies** in wp-admin (`manage_policies`, studio admin only):
- Create a policy; draft and edit version bodies
- Publish a draft version; view acceptance history per version

## REST API
| Method   | Endpoint                                                        | Permission        |
|----------|-----------------------------------------------------------------|-------------------|
| `GET`    | `/wp-json/us-scheduler/v1/policies`                             | Public (current published versions) |
| `POST`   | `/wp-json/us-scheduler/v1/policies`                             | `manage_policies` |
| `POST`   | `/wp-json/us-scheduler/v1/policies/{id}/versions`               | `manage_policies` |
| `PATCH`  | `/wp-json/us-scheduler/v1/policies/{id}/versions/{vid}`         | `manage_policies` |
| `POST`   | `/wp-json/us-scheduler/v1/policies/{id}/versions/{vid}/publish` | `manage_policies` |

Acceptances are not posted directly — they are written as part of `POST /bookings`
and `POST /enrollments` via the `accepted_policy_version_ids[]` field, which must
cover every policy's current version or the registration is rejected.

## Implementation
- Repositories: `Unsupervised\Schedular\Policy\PolicyRepository`, `Unsupervised\Schedular\Policy\PolicyVersionRepository`, `Unsupervised\Schedular\Policy\AcceptanceRepository`
- Models: `Unsupervised\Schedular\Policy\Policy`, `Unsupervised\Schedular\Policy\PolicyVersion`, `Unsupervised\Schedular\Policy\PolicyAcceptance`
- Service: `Unsupervised\Schedular\Policy\PolicyService` — orchestrates create / add-draft / publish across the policies and versions tables (archive prior current version, stamp `published_at`, repoint `current_version_id`)
- Admin controller: `Unsupervised\Schedular\Policy\PolicyController`
- REST endpoint: `Unsupervised\Schedular\Policy\PolicyEndpoint`

## Tests
- `tests/Unit/Policy/PolicyValueObjectsTest.php`
- `tests/Unit/Policy/PolicyRepositoryTest.php`
- `tests/Unit/Policy/PolicyVersionRepositoryTest.php`
- `tests/Unit/Policy/AcceptanceRepositoryTest.php`
- `tests/Unit/Policy/PolicyServiceTest.php`