pchelpmaster/docs/README.md

Документация разработчика

Здесь собрано всё, что нужно, чтобы разобраться в коде Pchelpcrm и начать его менять: решения, модель данных и руководство по каждой части приложения. Руководство растёт вместе с кодом: каждая новая фича добавляет или обновляет свою страницу.

Основы

Документ	О чём
architecture.md	общая схема, слои внутри фичи, DI, SSR и изоляция данных, nginx, UI-принципы
data-model.md	коллекции PocketBase, поля, правила доступа, публичный маршрут
testing.md	уровни тестов, тестовый PocketBase, контрактные тесты

Руководство (guide/)

Страницы появляются вместе с соответствующим кодом.

Страница	О чём
guide/project-structure.md	карта репозитория: src/app, pocketbase/, tests/, scripts/; где что искать
guide/adding-a-feature.md	пошаговый пример добавления новой сущности от миграции до экрана (на примере меток)
guide/shared.md	общая инфраструктура: клиент PocketBase, доменные ошибки, общие UI-компоненты
guide/auth.md	вход, регистрация, сессия, cookie, guard'ы, работа с текущим пользователем
guide/tags.md	метки: репозиторий, диалог управления, компонент выбора
guide/clients.md	клиенты: телефоны, поиск, форма, точки расширения карточки
guide/orders.md	заявки: статусы, фильтры, форма, вложения
guide/share.md	публичная ссылка и публичная страница
guide/ssr.md	как устроен серверный рендер: cookie, TransferState, что можно и нельзя на сервере
guide/ui.md	дизайн-токены, темы, общие компоненты, правила доступности

Как писать страницу руководства

Страница описывает часть приложения так, чтобы новый разработчик мог ей пользоваться, не читая весь код.

# <Фича>

Одно-два предложения: что делает фича и для чего.

## Где лежит
Дерево папок фичи с пояснением каждой важной папки и файла.

## Публичный API
Что экспортирует `index.ts`: абстрактные классы, типы, компоненты (селектор, входы, выходы), функции `provideXxx()`, токены расширения. По каждому — одна строка назначения.

## Как пользоваться
Короткие примеры кода для типовых задач: получить данные, встроить компонент, обработать ошибку.

## Как расширить или заменить
Как подменить реализацию через DI, как подключиться к точке расширения, что поменять при добавлении поля.

## Тесты
Где лежат тесты фичи, какой контракт у репозитория, какие фейки доступны.

## Подводные камни
Неочевидное: ограничения SSR, правила доступа, особенности PocketBase.

Правила:

• Пиши о том, что есть в коде сейчас, а не о планах. Если код меняется — страница меняется в том же коммите.
• Примеры кода должны быть рабочими и короткими; полный код — ссылкой на файл.
• Не дублируй architecture.md и data-model.md: ссылайся на нужный раздел.