pchelpmaster/docs/README.md

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

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

## Основы

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

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

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

| Страница                                                                 | О чём                                                                               |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `guide/project-structure.md`                                             | карта репозитория: `src/app`, `pocketbase/`, `tests/`, `scripts/`; где что искать   |
| `guide/adding-a-feature.md`                                              | пошаговый пример добавления новой сущности от миграции до экрана (на примере меток) |
| [guide/shared.md](guide/shared.md)                                       | общая инфраструктура: клиент PocketBase, доменные ошибки, общие UI-компоненты       |
| [guide/tests/api-harness.md](guide/tests/api-harness.md)                 | стенд API-тестов: Vitest в Node, `global-setup`, проверка типов                     |
| [guide/tests/integration-harness.md](guide/tests/integration-harness.md) | стенд интеграционных тестов: цель `test-integration` builder'а Angular              |
| [guide/tests/e2e-harness.md](guide/tests/e2e-harness.md)                 | стенд e2e: Playwright, два `webServer`, фикстуры, axe                               |
| [guide/tests/config-tests.md](guide/tests/config-tests.md)               | тесты конфигов: ESLint-границы, dev-прокси, Playwright                              |
| `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`                                                            | дизайн-токены, темы, общие компоненты, правила доступности                          |

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

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

```markdown
# <Фича>

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

## Где лежит

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

## Публичный API

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

## Как пользоваться

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

## Как расширить или заменить

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

## Тесты

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

## Подводные камни

Неочевидное: ограничения SSR, правила доступа, особенности PocketBase.
```

Правила:

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