mirror of
https://github.com/kamask-dev/pchelpmaster.git
synced 2026-11-11 05:49:38 +00:00
kamaskandClaude Sonnet 5.5
bec31ff02e
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014hvR7iG75jK5byaBBHdDLT
63 lines
4.5 KiB
Markdown
63 lines
4.5 KiB
Markdown
# Документация разработчика
|
|
|
|
Здесь собрано всё, что нужно, чтобы разобраться в коде Pchelpcrm и начать его менять: решения, модель данных и руководство по каждой части приложения. Руководство растёт вместе с кодом: каждая новая фича добавляет или обновляет свою страницу.
|
|
|
|
## Основы
|
|
|
|
| Документ | О чём |
|
|
| --- | --- |
|
|
| [architecture.md](architecture.md) | общая схема, слои внутри фичи, DI, SSR и изоляция данных, nginx, UI-принципы |
|
|
| [data-model.md](data-model.md) | коллекции PocketBase, поля, правила доступа, публичный маршрут |
|
|
| [testing.md](testing.md) | уровни тестов, тестовый PocketBase, контрактные тесты |
|
|
|
|
## Руководство (`guide/`)
|
|
|
|
Страницы появляются вместе с соответствующим кодом.
|
|
|
|
| Страница | О чём |
|
|
| --- | --- |
|
|
| `guide/project-structure.md` | карта репозитория: `src/app`, `pocketbase/`, `tests/`, `scripts/`; где что искать |
|
|
| `guide/adding-a-feature.md` | пошаговый пример добавления новой сущности от миграции до экрана (на примере меток) |
|
|
| [guide/shared.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` | дизайн-токены, темы, общие компоненты, правила доступности |
|
|
|
|
## Как писать страницу руководства
|
|
|
|
Страница описывает часть приложения так, чтобы новый разработчик мог ей пользоваться, не читая весь код.
|
|
|
|
```markdown
|
|
# <Фича>
|
|
|
|
Одно-два предложения: что делает фича и для чего.
|
|
|
|
## Где лежит
|
|
Дерево папок фичи с пояснением каждой важной папки и файла.
|
|
|
|
## Публичный API
|
|
Что экспортирует `index.ts`: абстрактные классы, типы, компоненты (селектор, входы, выходы), функции `provideXxx()`, токены расширения. По каждому — одна строка назначения.
|
|
|
|
## Как пользоваться
|
|
Короткие примеры кода для типовых задач: получить данные, встроить компонент, обработать ошибку.
|
|
|
|
## Как расширить или заменить
|
|
Как подменить реализацию через DI, как подключиться к точке расширения, что поменять при добавлении поля.
|
|
|
|
## Тесты
|
|
Где лежат тесты фичи, какой контракт у репозитория, какие фейки доступны.
|
|
|
|
## Подводные камни
|
|
Неочевидное: ограничения SSR, правила доступа, особенности PocketBase.
|
|
```
|
|
|
|
Правила:
|
|
|
|
- Пиши о том, что есть в коде сейчас, а не о планах. Если код меняется — страница меняется в том же коммите.
|
|
- Примеры кода должны быть рабочими и короткими; полный код — ссылкой на файл.
|
|
- Не дублируй `architecture.md` и `data-model.md`: ссылайся на нужный раздел.
|