# Модель данных (PocketBase)

Схема создаётся JS-миграциями в `pocketbase/pb_migrations/` (одна миграция на изменение, пишется руками, не через админку). Кастомные маршруты и хуки — в `pocketbase/pb_hooks/`.

У всех коллекций, кроме `users`, есть поле `owner` — ссылка на владельца. Это основа изоляции: любые правила доступа начинаются с `owner = @request.auth.id`.

Поля `id`, `created`, `updated` (autodate) есть у всех коллекций и ниже не перечисляются.

## users (auth-коллекция, уже существует в PocketBase)

| Поле       | Тип      | Ограничения                                                         |
| ---------- | -------- | ------------------------------------------------------------------- |
| `email`    | email    | обязательно, уникально без учёта регистра (индекс `COLLATE NOCASE`) |
| `password` | password | минимум 8 символов                                                  |
| `name`     | text     | необязательно, до 100 символов                                      |
| `verified` | bool     | системное; гость не может выставить `true`                          |

Формат email дополнительно проверяет хук `pb_hooks/users_email.pb.js` при любом сохранении записи: только печатные символы ASCII без пробелов, минимум один символ до `@`, один после `@`, точка и минимум два символа после неё. Поэтому кириллические адреса отклоняются (400, ошибка в поле `email`), а индекс `COLLATE NOCASE` покрывает все допустимые адреса.

Способ входа — только email + пароль (OAuth2, OTP, MFA выключены).

| Правило     | Значение                          | Смысл                             |
| ----------- | --------------------------------- | --------------------------------- |
| list / view | `id = @request.auth.id`           | пользователь видит только себя    |
| create      | `""` (всем)                       | открытая регистрация              |
| update      | `id = @request.auth.id`           | меняет только себя                |
| delete      | `null` (только суперпользователь) | удаление аккаунта в MVP не делаем |

Поле `avatar`, созданное PocketBase по умолчанию, можно оставить, в MVP оно не используется.

## tags — метки

Метки заменяют и категории, и источники заявок: «Установка Windows», «YouDo», «Профи.ру», «Сарафан», «Гарантия» — это всё метки. Набор у каждого пользователя свой.

| Поле    | Тип              | Ограничения                                                                                        |
| ------- | ---------------- | -------------------------------------------------------------------------------------------------- |
| `owner` | relation → users | обязательно, одна, `cascadeDelete: true`                                                           |
| `name`  | text             | обязательно, 1–50 символов                                                                         |
| `color` | select           | одно из: `gray`, `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`; обязательно |

Индекс: уникальный `(owner, name COLLATE NOCASE)` — у одного пользователя нет двух меток с одинаковым названием без учёта регистра; у разных пользователей названия могут совпадать.

Цвет — ключ из фиксированной палитры, а не произвольный HEX: так UI гарантирует контраст AA в светлой и тёмной теме.

## clients — клиенты

| Поле            | Тип              | Ограничения                                                                                                                                   |
| --------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `owner`         | relation → users | обязательно, `cascadeDelete: true`                                                                                                            |
| `name`          | text             | обязательно, 1–200 символов (как клиента зовут или как он подписан на площадке)                                                               |
| `phones`        | json             | массив нормализованных номеров (`["79991234567"]`), до 5 штук, можно пустой                                                                   |
| `email`         | email            | необязательно                                                                                                                                 |
| `contacts`      | text             | свободный текст до 2000 символов: мессенджеры и прочие контакты                                                                               |
| `external_urls` | json             | необязательно; массив ссылок на профили клиента на любых площадках (YouDo, Профи.ру, Avito и др.), до 5 штук, каждая — валидный `http(s)` URL |
| `address`       | text             | необязательно, до 500 символов                                                                                                                |
| `note`          | text             | внутренняя заметка, до 5000 символов                                                                                                          |

Нормализация телефона (делает фронтенд, функция в `clients/domain`): оставить только цифры; `8XXXXXXXXXX` → `7XXXXXXXXXX`; 10 цифр, начинающиеся на `9`, → добавить `7`. Остальные номера хранятся как есть (только цифры).

Удалить клиента, у которого есть заявки, нельзя (связь `orders.client` обязательная и без каскада): сначала удаляются или переносятся заявки.

## orders — заявки

| Поле           | Тип                | Ограничения                                                                                                                                                                                                                                                            |
| -------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `owner`        | relation → users   | обязательно, `cascadeDelete: true`                                                                                                                                                                                                                                     |
| `client`       | relation → clients | обязательно, одна, без каскада                                                                                                                                                                                                                                         |
| `title`        | text               | обязательно, 1–200 символов                                                                                                                                                                                                                                            |
| `description`  | text               | описание проблемы со слов клиента, до 10000                                                                                                                                                                                                                            |
| `status`       | select             | обязательно: `new`, `scheduled`, `in_progress`, `done`, `failed`                                                                                                                                                                                                       |
| `scheduled_at` | date               | дата и время визита, необязательно                                                                                                                                                                                                                                     |
| `address`      | text               | адрес выезда, до 500 (по умолчанию в форме подставляется адрес клиента)                                                                                                                                                                                                |
| `price`        | number             | целые рубли, ≥ 0, необязательно                                                                                                                                                                                                                                        |
| `result`       | text               | что сделано, до 10000; **виден по публичной ссылке**                                                                                                                                                                                                                   |
| `note`         | text               | примечания мастера, до 10000; **видны по публичной ссылке**                                                                                                                                                                                                            |
| `review`       | text               | отзыв клиента (например, с площадки), до 5000; **виден по публичной ссылке**                                                                                                                                                                                           |
| `external_url` | url                | необязательно; ссылка на страницу заказа на любой площадке (YouDo, Профи.ру, Avito и др.)                                                                                                                                                                              |
| `tags`         | relation → tags    | несколько, до 20, необязательно                                                                                                                                                                                                                                        |
| `attachments`  | file               | несколько, до 20 файлов, до 50 МБ каждый, **protected**; изображения (`image/jpeg`, `image/png`, `image/webp`, `image/heic`) и аудио (`audio/mpeg`, `audio/mp4`, `audio/x-m4a`, `audio/aac`, `audio/ogg`, `audio/wav`, `audio/webm`, `audio/amr`); миниатюры `200x200` |
| `share_token`  | text               | необязательно; если задан — 43 символа `[A-Za-z0-9_-]`; уникален среди непустых                                                                                                                                                                                        |

Статусы и подписи в UI:

| Значение      | Подпись       |
| ------------- | ------------- |
| `new`         | Новая         |
| `scheduled`   | Запланирована |
| `in_progress` | В работе      |
| `done`        | Выполнена     |
| `failed`      | Не выполнена  |

Переходы между статусами не ограничены: мастер может выставить любой.

Индексы: `owner`, `(owner, status)`, `(owner, created)`, уникальный частичный `share_token WHERE share_token != ''`.

### Соответствие полям YouDo (для справки)

| YouDo                | Pchelpcrm                  |
| -------------------- | -------------------------- |
| title, description   | `title`, `description`     |
| price                | `price`                    |
| address, privateInfo | `address`                  |
| customerName         | `clients.name`             |
| customerUrl          | `clients.external_urls`    |
| taskUrl              | `external_url`             |
| category             | метка                      |
| review               | `review`                   |
| taskDate             | `created` / `scheduled_at` |

## Правила доступа для tags, clients, orders

Общий шаблон (для `orders` добавляются проверки связей):

| Правило     | Значение                                                                                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------- |
| list / view | `owner = @request.auth.id`                                                                                    |
| create      | `@request.auth.id != "" && owner = @request.auth.id`                                                          |
| update      | `owner = @request.auth.id && (@request.body.owner:isset = false \|\| @request.body.owner = @request.auth.id)` |
| delete      | `owner = @request.auth.id`                                                                                    |

Дополнительно для `orders` (create и update):

- клиент принадлежит тому же пользователю: `client.owner = @request.auth.id`;
- все метки принадлежат тому же пользователю (для пустого списка условие выполняется).

Если какое-то условие невозможно выразить правилом, его реализуют хуком в `pocketbase/pb_hooks/`. Решение принимается при реализации, поведение фиксируют тесты.

### Как PocketBase отвечает на нарушения правил

API-тесты проверяют именно это поведение. Если фактический код в PocketBase 0.40 окажется другим, тесты фиксируют фактический, а главное требование неизменно: **чужие данные никогда не попадают в ответ и не меняются**.

| Операция | Правило не выполнено            | Правило `null` (не суперпользователь) |
| -------- | ------------------------------- | ------------------------------------- |
| list     | 200, чужие записи отфильтрованы | 403                                   |
| view     | 404                             | 403                                   |
| create   | 400                             | 403                                   |
| update   | 404                             | 403                                   |
| delete   | 404                             | 403                                   |

## Публичный маршрут

`GET /api/public/orders/{token}` (хук в `pocketbase/pb_hooks/`), без авторизации.

- Ищет заявку по непустому `share_token`, совпадающему точно.
- Ответ 200 содержит **только**: `title`, `description`, `result`, `note`, `review`, `status`, `scheduled_at`, `price`, `created`, `tags: [{ name, color }]`.
- Никогда не содержит: `id` заявки, `owner`, данные клиента (имя, телефоны, контакты, адрес, ссылки на профили), `address` заявки, `external_url`, `attachments`, `share_token`, email мастера.
- Нет заявки или токен пустой/неверного формата — 404 с одинаковым телом.
- Заголовки: `Cache-Control: no-store`, `X-Robots-Tag: noindex`.

Ссылку создаёт владелец, записывая в `share_token` случайную строку (32 случайных байта в base64url, сгенерированные в браузере через `crypto.getRandomValues`). Отключить ссылку — записать пустую строку; перевыпустить — записать новую.