mirror of
https://github.com/kamask-dev/pchelpmaster.git
synced 2026-11-11 05:49:38 +00:00
docs: rewrite claude.md and readme in russian, add architecture docs
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
kamask
co-authored by
Claude Sonnet 5.5
Claude Sonnet 5.5
parent
0f69a2f8a5
commit
38b38de929
@@ -1,102 +1,111 @@
|
||||
# Pchelpcrm
|
||||
|
||||
A CRM for handling service requests (orders) of a private service professional: computer help, home repairs, furniture assembly, plumbing, electrical work and similar jobs. The domain is generic, so any business where a client asks for a job to be done fits.
|
||||
CRM для частных мастеров: учёт клиентов и заявок для компьютерной помощи, мелкого ремонта, сборки мебели, сантехники, электрики и любых других работ «клиент обратился — работа выполнена».
|
||||
|
||||
## Concepts
|
||||
Система многопользовательская: каждый мастер регистрируется сам и работает только со своими данными.
|
||||
|
||||
- **User** — the account owner who works in the CRM. Signs in with email and password (PocketBase auth). Data of each user is isolated from others.
|
||||
- **Client** — a customer of the user.
|
||||
- **Request** — a service request (order). Belongs to one client; a client can have many requests.
|
||||
- **Category** — a request category. Dynamic: created and edited by the user.
|
||||
## Возможности
|
||||
|
||||
## Stack
|
||||
- Регистрация и вход по email и паролю.
|
||||
- Клиенты: телефоны, контакты, адрес, ссылки на профили на площадках, заметка; поиск по имени и телефону; история заявок клиента.
|
||||
- Заявки: статус, дата визита, адрес, сумма, что сделано, примечания мастера, отзыв клиента, ссылка на заказ на площадке, фото и аудио.
|
||||
- Метки вместо категорий и источников: мастер сам заводит «Установка Windows», «YouDo», «Сарафан» и вешает на заявку сколько угодно.
|
||||
- Поиск и фильтры заявок по тексту, статусу, меткам и периоду.
|
||||
- Публичная ссылка на заявку для клиента: суть работы без данных клиента и вложений.
|
||||
- Серверный рендер главной, карточки заявки и публичной страницы.
|
||||
|
||||
- [Angular](https://angular.dev/) — frontend, generated with [Angular CLI](https://github.com/angular/angular-cli) 22.2.3
|
||||
- [PocketBase](https://pocketbase.io/) — backend, database and authentication
|
||||
- [pnpm](https://pnpm.io/) — package manager
|
||||
## Понятия
|
||||
|
||||
## Distribution
|
||||
| Понятие | Что это |
|
||||
| --- | --- |
|
||||
| Пользователь | мастер, владелец аккаунта |
|
||||
| Клиент | заказчик мастера |
|
||||
| Заявка (`Order`) | заказ; принадлежит одному клиенту, у клиента может быть много заявок |
|
||||
| Метка (`Tag`) | ярлык заявки, который мастер создаёт сам |
|
||||
| Публичная ссылка | страница заявки для клиента по случайному токену |
|
||||
|
||||
After the first release the application will be shipped as a single Docker container (the app and PocketBase together, no docker-compose) that can be deployed to a production server.
|
||||
## Стек
|
||||
|
||||
## Development server
|
||||
- [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/) — тесты
|
||||
|
||||
To start a local development server, run:
|
||||
## Быстрый старт
|
||||
|
||||
Нужны Node.js 22+, pnpm и бинарник [`pocketbase`](https://pocketbase.io/docs/) 0.40.x в `PATH`.
|
||||
|
||||
```bash
|
||||
ng serve
|
||||
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/
|
||||
```
|
||||
|
||||
Once the server is running, open your browser and navigate to `http://localhost:4200/`. The application will automatically reload whenever you modify any of the source files.
|
||||
В разработке браузер обращается к PocketBase по пути `/pb/*`, его проксирует dev-сервер Angular.
|
||||
|
||||
## Code scaffolding
|
||||
## Команды
|
||||
|
||||
Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
|
||||
| Команда | Что делает |
|
||||
| --- | --- |
|
||||
| `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` | создать суперпользователя или сбросить его пароль |
|
||||
|
||||
```bash
|
||||
ng generate component component-name
|
||||
Тесты, которым нужен 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/ документация разработчика
|
||||
```
|
||||
|
||||
For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
|
||||
## Документация
|
||||
|
||||
Документация разработчика лежит в [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
|
||||
ng generate --help
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
To build the project run:
|
||||
|
||||
```bash
|
||||
ng build
|
||||
```
|
||||
|
||||
This will compile your project and store the build artifacts in the `dist/` directory. By default, the production build optimizes your application for performance and speed.
|
||||
|
||||
## Running unit tests
|
||||
|
||||
To execute unit tests with the [Vitest](https://vitest.dev/) test runner, use the following command:
|
||||
|
||||
```bash
|
||||
ng test
|
||||
```
|
||||
|
||||
## Running end-to-end tests
|
||||
|
||||
For end-to-end (e2e) testing, run:
|
||||
|
||||
```bash
|
||||
ng e2e
|
||||
```
|
||||
|
||||
Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
|
||||
|
||||
## PocketBase
|
||||
|
||||
The backend is [PocketBase](https://pocketbase.io/) (v0.40.x). The `pocketbase` binary must be in `PATH`.
|
||||
|
||||
- `pocketbase/pb_migrations/` — collection schema as JS migrations (committed).
|
||||
- `pocketbase/pb_data/` — local dev database (not committed).
|
||||
|
||||
Local development:
|
||||
|
||||
```bash
|
||||
cp .env.example .env # then set PB_SUPERUSER_EMAIL / PB_SUPERUSER_PASSWORD
|
||||
pnpm pb:superuser # create the superuser or reset its password (safe to re-run)
|
||||
pnpm pb:serve # http://127.0.0.1:8090, admin UI at /_/
|
||||
```
|
||||
|
||||
Migrations are applied on `pb:serve` start (or explicitly with `pnpm pb:migrate`). Schema changes made in the dev admin UI are written to `pocketbase/pb_migrations/` automatically — commit them.
|
||||
|
||||
Production uses the same binary version and the same `pb_migrations/`, with its own data dir:
|
||||
|
||||
```bash
|
||||
pocketbase serve --dir /path/to/pb_data --migrationsDir pocketbase/pb_migrations --automigrate=false --http 127.0.0.1:8090
|
||||
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
|
||||
```
|
||||
|
||||
Back up by copying the `pb_data` directory.
|
||||
| Переменная | Назначение |
|
||||
| --- | --- |
|
||||
| `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` и тесты) |
|
||||
|
||||
## Additional Resources
|
||||
|
||||
For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
|
||||
Резервная копия — копирование папки `pb_data`. После первого релиза приложение планируется поставлять одним Docker-контейнером (SSR-сервер и PocketBase вместе).
|
||||
|
||||
Reference in New Issue
Block a user