# Архитектура Архитектурные решения проекта. Если код или новая задача им противоречит, сначала обсуждается и правится этот документ. ## 1. Общая схема ``` ┌─ location /pb/ ─(префикс /pb срезается)─► PocketBase :8090 Браузер ──► nginx ──┤ ▲ └─ location / ──► Node SSR-сервер :4200 ────────┘ (src/server.ts) PB_URL — напрямую, без nginx ``` - Браузер ходит в PocketBase по пути `/pb/*` своего origin: SDK создаётся с адресом `/pb`, запрос `/pb/api/collections/...` nginx отправляет в PocketBase как `/api/collections/...`. - Node SSR-сервер при рендере обращается к PocketBase напрямую по внутреннему адресу `PB_URL`. - В разработке nginx нет: его роль для `/pb/*` выполняет прокси dev-сервера Angular (`proxy.conf.mjs`). - **PocketBase** — единственный бэкенд: база, авторизация, файлы, правила доступа (API rules), кастомные маршруты (`pocketbase/pb_hooks/`). Это же и публичный API для будущих клиентов (мобильное приложение, Telegram-бот, десктоп). - **Безопасность данных обеспечивает PocketBase**, а не фронтенд. Фронтенд может быть скомпрометирован или заменён другим клиентом, поэтому изоляция пользователей проверяется API-тестами на уровне правил коллекций. - **SSR-сервер** только рендерит страницы и отдаёт статику, API PocketBase он не проксирует. Браузер всегда обращается к своему origin (nginx): нет CORS, cookie общая для приложения. ## 2. Слои и структура папок Код организован по фичам (`src/app//`). Внутри фичи — слои в духе DDD: ``` src/app/orders/ index.ts ← публичный API фичи: что можно импортировать другим фичам orders.routes.ts ← маршруты фичи (lazy) provide-orders.ts ← provideOrders(): регистрация реализаций в DI domain/ ← чистый TypeScript, без Angular и без PocketBase order.ts ← модель (типы) order-status.ts ← статусы и подписи order-filter.ts ← параметры фильтрации/поиска order-repository.ts ← abstract class OrderRepository (контракт и DI-токен) data/ ← реализация контрактов через PocketBase pocketbase-order-repository.ts order-mapper.ts ← запись PocketBase ⇄ доменная модель ui/ ← компоненты (одна папка на компонент, если есть html/css) order-list/order-list.ts order-form/order-form.ts testing/ ← фейки для тестов других слоёв и фич in-memory-order-repository.ts ``` Правила: 1. **domain** не импортирует ничего из `@angular/*`, `pocketbase`, `data/`, `ui/`. Здесь только типы, чистые функции и абстрактные классы. 2. **data** знает про PocketBase и домен. Наружу отдаёт только доменные типы: запись PocketBase (`RecordModel`) не покидает слой `data`. 3. **ui** знает только домен и абстрактные классы. Компоненты никогда не импортируют `pocketbase` и `data/`. 4. Фича импортирует другую фичу **только через её `index.ts`**. Глубокие импорты (`../clients/data/...`) запрещены. 5. Общая инфраструктура, нужная всем фичам, живёт в `src/app/shared/` (например `shared/pocketbase/`, позже `shared/ui/`). Туда кладём только то, что реально используется двумя и более фичами. ### Фичи MVP | Папка | Назначение | | -------------------- | ---------------------------------------------------------------------------------------- | | `shared/pocketbase/` | URL PocketBase, фабрика клиента, синхронизация cookie, маппинг ошибок | | `users/` | сущность User (профиль владельца аккаунта), без логики входа | | `auth/` | сессия: вход, регистрация, выход, текущий пользователь, guard'ы, формы входа/регистрации | | `layout/` | каркас приложения: шапка, навигация, меню пользователя | | `home/` | главная страница: лендинг для гостя или список заявок для вошедшего | | `tags/` | метки пользователя: диалог управления метками и компонент выбора меток | | `clients/` | клиенты | | `orders/` | заявки, вложения | | `share/` | публичная ссылка и публичная страница заявки | | `not-found/` | страница 404 | ### Направление зависимостей между фичами ``` home ──► orders ──► clients ──► shared │ │ └───► tags ─────► shared │ └──────► share ────► shared └──► auth ──► users ``` - Зависимости идут только в одну сторону, циклов нет. - Если «нижней» фиче нужно показать что-то из «верхней» (например, история заявок в карточке клиента), нижняя объявляет точку расширения — `InjectionToken` со списком компонентов, — а верхняя регистрирует в ней свой компонент в `provideXxx()`. Так `clients` ничего не знает о заявках. > Сущность заявки в коде называется **`Order`**; коллекция, папка и маршруты — `orders`. ## 3. Dependency Injection через абстрактные классы Каждый репозиторий и сервис, у которого может появиться другая реализация, описан **абстрактным классом**. Абстрактный класс одновременно контракт и DI-токен. ```ts // tags/domain/tag-repository.ts export abstract class TagRepository { abstract list(): Promise; abstract create(draft: TagDraft): Promise; abstract update(id: string, changes: Partial): Promise; abstract delete(id: string): Promise; } // tags/provide-tags.ts export function provideTags(): Provider[] { return [{ provide: TagRepository, useClass: PocketBaseTagRepository }]; } // app.config.ts — единственное место, где выбираются реализации providers: [ providePocketBase(), provideAuth(), provideTags(), provideClients(), provideOrders(), provideShare(), ]; ``` - Компоненты и сервисы получают зависимость так: `private readonly tags = inject(TagRepository);`. - Чтобы поменять реализацию, достаточно изменить `provideXxx()` или `app.config.ts`. - В unit-тестах вместо PocketBase подставляется фейк из `testing/`: `{ provide: TagRepository, useClass: InMemoryTagRepository }`. - Методы репозиториев возвращают `Promise` (PocketBase SDK промис-ориентирован). В компонентах данные загружаются через `resource()`: так SSR дожидается загрузки (resource регистрирует pending task), а состояние доступно как сигналы. - Отдельного слоя сторов нет. Стор (сервис с состоянием на сигналах) заводится только там, где одно состояние реально разделяют несколько компонентов, например список меток для диалога управления, компонента выбора и фильтров. ## 4. Ошибки `shared/pocketbase/` переводит `ClientResponseError` в доменные ошибки, которые понимает UI: | Доменная ошибка | Когда | | ------------------- | -------------------------------------------------------------------------------- | | `NotFoundError` | 404 (в том числе «чужая запись»: PocketBase не различает «нет» и «нет доступа») | | `ValidationError` | 400 с ошибками по полям: `fieldErrors: Record` (коды PocketBase) | | `UnauthorizedError` | 401/403: сессия недействительна | | `NetworkError` | нет связи / PocketBase недоступен | UI показывает ошибки полей рядом с полями, а общие ошибки — в области уведомлений с `role="alert"`. ## 5. Аутентификация - Вход и регистрация по email и паролю через коллекцию `users` (PocketBase auth). Регистрация открытая. Подтверждение email и сброс пароля в MVP не делаются. - Токен PocketBase (JWT) хранится в **cookie `pb_auth`** (`Path=/`, `SameSite=Lax`, `Secure` на HTTPS). Cookie нужна, чтобы SSR-сервер знал, кто пришёл. - Cookie **не `HttpOnly`**: браузерному SDK нужен токен для прямых запросов в `/pb/api`. Риск — кража токена при XSS. Снижаем его так: Angular экранирует шаблоны, нигде не используется `innerHTML` с пользовательскими данными, позже добавим CSP. Это осознанный компромисс MVP. - В браузере: при изменении `authStore` cookie перезаписывается (`exportToCookie`); при старте приложения, если токен есть, вызывается `authRefresh()`; при ошибке — выход. - На сервере: токен читается из заголовка `Cookie` текущего запроса (`loadFromCookie`). Сервер cookie не пишет и токен не обновляет. ## 6. SSR и изоляция данных пользователей ### Какие маршруты как рендерятся | Маршрут | Режим | Почему | | --------------------------------------- | ------ | ------------------------------------------------- | | `/` | Server | лендинг для гостя или список заявок для вошедшего | | `/orders/:id` | Server | карточка заявки | | `/p/:token` | Server | публичная страница заявки (превью в мессенджерах) | | остальные (`/clients/**`, формы заявок) | Client | интерактивные формы, SSR не даёт выгоды | Настраивается в `src/app/app.routes.server.ts`. ### Правила, без которых данные пользователей могут перемешаться На сервере каждый HTTP-запрос получает **свой экземпляр Angular-приложения и свой root-инжектор**. Всё, что живёт в DI, изолировано. Опасно только то, что живёт **вне DI** — на уровне модуля, общее для всех запросов. 1. **Нельзя** создавать PocketBase на уровне модуля (`export const pb = new PocketBase(...)`). Экземпляр создаёт только фабрика в `shared/pocketbase/` внутри DI. ESLint-правило запрещает `new PocketBase(` во всех остальных файлах. 2. **Нельзя** хранить пользовательские данные в переменных модуля, статических полях классов, кэшах вне DI. 3. Сервер рендерит страницы с заголовками `Cache-Control: private, no-store` и `Vary: Cookie`: ни браузер, ни прокси не должны отдать одну страницу двум людям. 4. На сервере используется глобальный `fetch` без общего состояния; `authStore` — свой у каждого экземпляра PocketBase (не `LocalAuthStore`, а in-memory `BaseAuthStore`). 5. Защищённые файлы (вложения) не рендерятся на сервере: их URL содержит короткоживущий токен, ему не место в HTML. 6. Изоляция проверяется e2e-тестами: параллельные SSR-запросы двух пользователей не видят данных друг друга. ### Гидратация PocketBase SDK использует `fetch`, а не `HttpClient`, поэтому встроенный HTTP transfer cache Angular не работает. Чтобы после гидратации не загружать данные второй раз, используется `TransferState`. ## 7. URL PocketBase - **Сервер:** `PB_URL` — переменная окружения Node-сервера, внутренний адрес PocketBase для серверного рендера (по умолчанию `http://127.0.0.1:8090`). В браузер не передаётся. - **Браузер:** `/pb`. Префикс `/pb` — константа `PB_PUBLIC_PATH` в `shared/pocketbase/`; если путь в nginx поменяется, меняется только она. - Всё это задаётся в одном месте: `shared/pocketbase/` (InjectionToken `PB_URL`, разные провайдеры для сервера и браузера). - **Разработка:** `ng serve` проксирует `/pb/*` → `PB_URL` со срезанием префикса (`proxy.conf.mjs`). E2E-тесты production-сборки используют маленький тестовый фронт-прокси, повторяющий правила nginx. ### Ожидаемая конфигурация nginx (пример, деплой — вне MVP) ```nginx location /pb/ { proxy_pass http://127.0.0.1:8090/; # слэш в конце срезает префикс /pb proxy_http_version 1.1; proxy_set_header Connection ''; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_buffering off; # для realtime (SSE) PocketBase proxy_read_timeout 360s; client_max_body_size 60M; # один файл вложения до 50 МБ + запас } location / { proxy_pass http://127.0.0.1:4000; # Node SSR-сервер proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } ``` - Вложения загружаются по одному файлу на запрос, чтобы укладываться в `client_max_body_size`. - В настройках PocketBase нужно указать доверенный заголовок реального IP (`X-Real-IP`), иначе лимиты запросов и логи будут видеть IP nginx. - Админку PocketBase удобнее открывать напрямую на порту 8090 (через SSH-туннель), а не через `/pb/_/`. ## 8. Формы и UI - Формы — Signal Forms (`@angular/forms/signals`) со схемами валидации. - Стили — чистый CSS: дизайн-токены в CSS custom properties (`src/styles.css`), тёмная тема по `prefers-color-scheme`, никаких препроцессоров и CSS-фреймворков. - Префикс селекторов компонентов и директив — `ksk` (`ksk-order-list`, `kskAutofocus`). - Минимальная нагрузка на GPU — приложение должно быть лёгким на слабых телефонах и ноутбуках: - анимируются только `transform` и `opacity`, коротко (до 200 мс); при `prefers-reduced-motion: reduce` анимации отключаются; - без `backdrop-filter`, `filter: blur()`, больших и многослойных `box-shadow`, анимированных градиентов, `background-attachment: fixed`; - `will-change` — только точечно и временно, не «на всякий случай»; - тени — одна мягкая тень из токенов; глубину лучше передавать фоном поверхности и границей; - длинные списки — `content-visibility: auto` с `contain-intrinsic-size`, чтобы не рендерить невидимое. - Интерфейс только на русском, без i18n-фреймворка. Даты и суммы форматируются в локали `ru-RU`, валюта — рубли. - Mobile-first: мастер часто работает с телефона. - Доступность: AXE без ошибок, WCAG AA. ## 9. Что сознательно отложено Подтверждение email и сброс пароля, инвайты, публичный профиль мастера, отчёты и финансы, напоминания, импорт/экспорт, Docker и деплой, мобильное приложение, бот. Архитектура их не блокирует: всё общение с данными идёт через PocketBase API и его правила.