mirror of
https://github.com/kamask-dev/pchelpmaster.git
synced 2026-11-11 05:49:38 +00:00
kamaskandClaude Sonnet 5.5
1109f68e11
- add tsconfig.tests.json and run tsc in test:api - move vitest ProvidedContext types to provided-context.d.ts - rename vitest.api.config.ts to .mts - kill signal-test fixture with SIGTERM first so cleanup still runs - add tests: no files in pb_migrations, independent user/guest clients - docs: drop superuser env vars from tests in README, note tsc in testing.md Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EvmtStx737hu8gXe15e55W
112 lines
8.6 KiB
Markdown
112 lines
8.6 KiB
Markdown
# Pchelpcrm
|
||
|
||
CRM для частных мастеров: учёт клиентов и заявок для компьютерной помощи, мелкого ремонта, сборки мебели, сантехники, электрики и любых других работ «клиент обратился — работа выполнена».
|
||
|
||
Система многопользовательская: каждый мастер регистрируется сам и работает только со своими данными.
|
||
|
||
## Возможности
|
||
|
||
- Регистрация и вход по email и паролю.
|
||
- Клиенты: телефоны, контакты, адрес, ссылки на профили на площадках, заметка; поиск по имени и телефону; история заявок клиента.
|
||
- Заявки: статус, дата визита, адрес, сумма, что сделано, примечания мастера, отзыв клиента, ссылка на заказ на площадке, фото и аудио.
|
||
- Метки вместо категорий и источников: мастер сам заводит «Установка Windows», «YouDo», «Сарафан» и вешает на заявку сколько угодно.
|
||
- Поиск и фильтры заявок по тексту, статусу, меткам и периоду.
|
||
- Публичная ссылка на заявку для клиента: суть работы без данных клиента и вложений.
|
||
- Серверный рендер главной, карточки заявки и публичной страницы.
|
||
|
||
## Понятия
|
||
|
||
| Понятие | Что это |
|
||
| ---------------- | -------------------------------------------------------------------- |
|
||
| Пользователь | мастер, владелец аккаунта |
|
||
| Клиент | заказчик мастера |
|
||
| Заявка (`Order`) | заказ; принадлежит одному клиенту, у клиента может быть много заявок |
|
||
| Метка (`Tag`) | ярлык заявки, который мастер создаёт сам |
|
||
| Публичная ссылка | страница заявки для клиента по случайному токену |
|
||
|
||
## Стек
|
||
|
||
- [Angular](https://angular.dev/) 22 с SSR, чистый CSS
|
||
- [PocketBase](https://pocketbase.io/) 0.40 — база данных, аутентификация, файлы и API
|
||
- [pnpm](https://pnpm.io/)
|
||
- [Vitest](https://vitest.dev/) и [Playwright](https://playwright.dev/) — тесты
|
||
|
||
## Быстрый старт
|
||
|
||
Нужны Node.js 22+, pnpm и бинарник [`pocketbase`](https://pocketbase.io/docs/) 0.40.x в `PATH`.
|
||
|
||
```bash
|
||
pnpm install
|
||
cp .env.example .env # заполнить PB_SUPERUSER_EMAIL и PB_SUPERUSER_PASSWORD
|
||
pnpm pb:superuser # создать суперпользователя PocketBase
|
||
pnpm pb:serve # PocketBase на http://127.0.0.1:8090, админка — /_/
|
||
pnpm start # приложение на http://localhost:4200/
|
||
```
|
||
|
||
В разработке браузер обращается к PocketBase по пути `/pb/*`, его проксирует dev-сервер Angular.
|
||
|
||
## Команды
|
||
|
||
| Команда | Что делает |
|
||
| ----------------------- | -------------------------------------------------------------------- |
|
||
| `pnpm start` | dev-сервер приложения |
|
||
| `pnpm build` | production-сборка в `dist/` |
|
||
| `pnpm lint` | ESLint |
|
||
| `pnpm test` | unit-тесты |
|
||
| `pnpm test:api` | API-тесты PocketBase: схема, правила доступа, изоляция пользователей |
|
||
| `pnpm test:integration` | репозитории приложения против тестового PocketBase |
|
||
| `pnpm e2e` | сценарии в браузере и проверка доступности (axe) |
|
||
| `pnpm e2e:prod` | сценарии на production-сборке |
|
||
| `pnpm pb:serve` | PocketBase для разработки |
|
||
| `pnpm pb:migrate` | применить миграции |
|
||
| `pnpm pb:superuser` | создать суперпользователя или сбросить его пароль |
|
||
|
||
Тесты, которым нужен PocketBase, сами поднимают временный экземпляр и не трогают `pocketbase/pb_data`. Перед первым запуском e2e установите браузер: `pnpm exec playwright install chromium`.
|
||
|
||
## Структура репозитория
|
||
|
||
```
|
||
src/
|
||
app/ приложение Angular, по папке на фичу (auth, clients, orders, tags, share, …)
|
||
server.ts Node SSR-сервер
|
||
pocketbase/
|
||
pb_migrations/ схема базы данных (JS-миграции)
|
||
pb_hooks/ кастомные маршруты и хуки PocketBase
|
||
pb_data/ локальная база (не в git)
|
||
tests/
|
||
api/ API-тесты PocketBase
|
||
e2e/ браузерные тесты
|
||
support/ тестовый PocketBase и хелперы
|
||
scripts/ служебные скрипты
|
||
docs/ документация разработчика
|
||
```
|
||
|
||
## Документация
|
||
|
||
Документация разработчика лежит в [docs/](docs/README.md):
|
||
|
||
- [architecture.md](docs/architecture.md) — общая схема, слои, DI, SSR и изоляция данных, nginx, принципы UI;
|
||
- [data-model.md](docs/data-model.md) — коллекции PocketBase, поля и правила доступа;
|
||
- [testing.md](docs/testing.md) — уровни тестов и тестовый PocketBase;
|
||
- `docs/guide/` — руководство по каждой части приложения: где лежит код, как им пользоваться и как его расширить. Пополняется вместе с кодом.
|
||
|
||
## Production
|
||
|
||
Схема: nginx отдаёт `/pb/*` в PocketBase (префикс `/pb` срезается), всё остальное — в Node SSR-сервер. Пример конфигурации nginx — в [docs/architecture.md](docs/architecture.md#7-url-pocketbase).
|
||
|
||
```bash
|
||
pnpm build
|
||
pocketbase serve --dir /path/to/pb_data --migrationsDir pocketbase/pb_migrations --hooksDir pocketbase/pb_hooks --automigrate=false --http 127.0.0.1:8090
|
||
PB_DIR=/path/to/pb_data node --env-file=.env scripts/pb-superuser.mjs
|
||
PB_URL=http://127.0.0.1:8090 PORT=4000 node dist/pchelpcrm/server/server.mjs
|
||
```
|
||
|
||
| Переменная | Назначение |
|
||
| --------------------------------------------- | ---------------------------------------------------------------------------------------------- |
|
||
| `PB_URL` | внутренний адрес PocketBase для SSR-сервера и dev-прокси, по умолчанию `http://127.0.0.1:8090` |
|
||
| `PORT` | порт Node SSR-сервера, по умолчанию `4000` |
|
||
| `PB_DIR` | папка данных PocketBase для скрипта `pb:superuser` |
|
||
| `PB_SUPERUSER_EMAIL`, `PB_SUPERUSER_PASSWORD` | суперпользователь PocketBase (скрипт `pb:superuser`) |
|
||
|
||
Резервная копия — копирование папки `pb_data`. После первого релиза приложение планируется поставлять одним Docker-контейнером (SSR-сервер и PocketBase вместе).
|