172 lines
14 KiB
Markdown
172 lines
14 KiB
Markdown
# building-mgmt-web — веб приложения «Обслуживание зданий»
|
||
|
||
Простой HTML+JS **без сборки и зависимостей** для
|
||
building-mgmt-backend: логин, заявки (фильтры/страницы/переходы/журнал),
|
||
проекты (объекты и мастера), приглашения, фотоотчёт (S3), самостоятельное
|
||
взятие заявки мастером, создание клиентов админом, разделы админа
|
||
«Мастера» и «Клиенты» с удалением/отключением аккаунтов и сбросом
|
||
пароля (ссылкой либо напрямую), удаление проекта админом.
|
||
|
||
Стек: чистые ES-модули в два файла (`js/api.js` — транспорт,
|
||
`js/app.js` — экраны), статику отдаёт nginx в контейнере.
|
||
|
||
## Запуск (3 шага)
|
||
|
||
```powershell
|
||
# 1. БД + API (в репо building-mgmt-backend)
|
||
docker compose up -d # postgres на :5433
|
||
go run ./cmd/migrate # миграции (0001..0016)
|
||
go run ./cmd/seed --force --yes # демо-данные (пароль demo-password-123)
|
||
go run ./cmd/api # API на :8080
|
||
|
||
# 2. Веб (здесь)
|
||
docker compose up -d # nginx на :3000
|
||
|
||
# 3. Браузер
|
||
# http://localhost:3000
|
||
```
|
||
|
||
Фронт ходит в API **на том же origin** (`BASE=''` в `js/api.js`):
|
||
nginx проксирует API-пути (`/auth`, `/users`, `/tickets`, …) на бэкенд
|
||
`host.docker.internal:8080` — см. `nginx.conf`. Поэтому CORS не нужен,
|
||
но `CORS_ORIGINS` в `.env` бэкенда безвреден (страховка для прямых
|
||
обращений на :8080). Прокси перезаписывает `X-Forwarded-For` — для
|
||
бэкенда это значит: укажите `TRUSTED_PROXIES` (подсеть docker) в `.env`
|
||
бэкенда, и лимиты/логи увидят реальный IP.
|
||
|
||
Правки `index.html`/`js/*`/`css/*` видны после **F5** — контейнер
|
||
монтирует каталог напрямую, пересборка не нужна. Правка `nginx.conf`
|
||
видна после перезапуска контейнера: `docker compose restart`.
|
||
|
||
## Прод-образ и CI
|
||
|
||
- `Dockerfile` — прод-образ: статика копируется внутрь (в деве она
|
||
монтируется bind-mount'ом), конфиг — `nginx.prod.conf`. Сборка:
|
||
`docker build -t building-mgmt-web:latest .`
|
||
- `nginx.prod.conf` — отличия от dev `nginx.conf`: прокси API на
|
||
контейнер `api` (`http://api:8080` внутри сети compose, вместо
|
||
`host.docker.internal:8080`) и security-заголовки
|
||
(nosniff/frame/referrer) поверх HSTS. Образ входит в стек
|
||
`compose.prod.yaml` репо бэкенда: наружу стек отдаёт только этот
|
||
nginx (порт 80, TLS-терминал перед ним), postgres/API/minio видны
|
||
только внутри сети.
|
||
- `.gitea/workflows/ci.yml` — CI/CD через **Gitea Actions** (встроенный в
|
||
Gitea): push/PR делают `node --check` и собирают образ
|
||
`building-mgmt-web:latest`+SHA (локальные теги, без реестра);
|
||
**деплой — только ручным запуском** workflow (кнопка Run workflow):
|
||
шаг скачивает compose-файлы репо бэкенда по API (секреты репо
|
||
`CI_HOST`/`CI_USER`/`CI_TOKEN`) и перезапускает web-сервис
|
||
стека свежим образом. Подробности — README бэкенда, раздел
|
||
«CI/CD (Gitea Actions)».
|
||
|
||
## Демо-аккаунты
|
||
|
||
| Роль | Email | Что проверять |
|
||
|---|---|---|
|
||
| клиент | `demo@example.com` | заявки, проекты, приглашение мастеров |
|
||
| мастер | `demo-worker@example.com` | назначенные заявки, переходы, приглашения |
|
||
| мастер 2 | `demo-worker2@example.com` | приглашение → принять/отклонить |
|
||
| админ | `demo-admin@example.com` | все проекты/заявки, сброс пароля мастерам и клиентам (ссылкой либо напрямую), разделы «Мастера» и «Клиенты» |
|
||
|
||
Пароль у всех: `demo-password-123` (вводится на экране входа вручную).
|
||
|
||
## Сценарий для проверки логики
|
||
|
||
1. **Клиент** → «Проекты» → «Демо-проект» → в блоке «Пригласить мастера»
|
||
**поиск по имени/email** (например, `demo-worker2` — он уже в базе, но
|
||
свободен) → «Пригласить». Либо создать нового мастера прямо в форме.
|
||
2. **Мастер 2** → «Приглашения» → «Принять».
|
||
3. **Клиент** → «Заявки» → «+ Новая заявка» (компактное модальное окно
|
||
поверх списка: закрывается крестиком, Escape или кликом по фону;
|
||
галочка «Повторяющаяся заявка» открывает **отдельное окно условий
|
||
повтора** — дата-время первого запуска и период в днях/неделях, см. 11а) → в деталях «Назначить»
|
||
(мастер обязан быть принявшим приглашение — иначе 400 с объяснением).
|
||
В таблице «Мастера» проекта есть локальный фильтр по имени/email.
|
||
3а. **Мастер** видит в списке свободные заявки своих проектов (бейдж «новая»)
|
||
и берёт их кнопкой «Взять заявку» — дальше «Начать работу» как обычно.
|
||
4. **Мастер** → «Начать работу» → «Работа выполнена». Фотоотчёт — только
|
||
в работе: после «Работа выполнена» загрузка и удаление закрыты
|
||
(после отклонения клиентом открываются снова со «Начать работу»).
|
||
5. **Клиент** → «Принять работу» (или «Отклонить» с причиной — тогда
|
||
мастер на заявке «на доработке» видит баннер с причиной и кнопку
|
||
«Начать работу»: берёт второй круг, после переделки снова «Работа
|
||
выполнена», и клиент принимает работу).
|
||
6. Журнал событий под заявкой показывает всю хронологию с авторами.
|
||
7. **Админ** → «Клиенты» → «+ Клиент»: создание аккаунта клиента —
|
||
единственный способ завести клиента (саморегистрации нет).
|
||
8. **Админ** → «Мастера»/«Клиенты» → в строке: «Сброс пароля» — окно с
|
||
двумя способами: «Выпустить ссылку» (одноразовый адрес
|
||
`#/reset-password?token=…`, живёт 24 часа, кнопка «Копировать» —
|
||
адрес передаётся пользователю сам) либо «Задать пароль напрямую»
|
||
(сервер ставит его сразу: все сессии пользователя закрываются,
|
||
неиспользованные токены сброса гаснут). Кнопку видит только админ —
|
||
раздел «Мастера» есть и у клиента, а эндпоинт закрыт ролью.
|
||
Дальше в строке: «Удалить» (чистый
|
||
аккаунт удаляется; есть заявки/проекты → диалог «Отключить вместо
|
||
удаления?»), «Отключить»/«Включить». Отключённые остаются в списке
|
||
с бейджем «отключён» и включаются обратно.
|
||
9. **Клиент** → «Проекты» → проект → «Мастера»: «Отключить» (мастер
|
||
теряет доступ во всех проектах) и «Убрать» (из проекта) — обе кнопки
|
||
с подтверждением; отключённый мастер виден с бейджем «отключён».
|
||
10. **Вход** → «Забыли пароль?» → email → письмо со ссылкой →
|
||
`#/reset-password?token=…` → новый пароль. Ответ сервера одинаков
|
||
для существующего и несуществующего адреса, так что перебор
|
||
ящиков не работает; 4 попытки подряд → 429.
|
||
11. **Админ** → «Проекты» → проект → «Удалить проект»: подтверждение
|
||
предупреждает, что вместе с проектом уйдут объекты, участия мастеров
|
||
и все заявки. У клиента кнопки нет (роут закрыт ролью `admin`),
|
||
повторное удаление — 404.
|
||
11а. **Клиент** → «Заявки» → «+ Новая заявка» → галочка
|
||
«Повторяющаяся заявка» открывает **отдельное окно с условиями
|
||
повтора**: **дата-время первого запуска** (нативный календарь, по
|
||
умолчанию «сейчас + 7 дней, 10:00»), **период** — «каждые N
|
||
дней/недель» (единицы согласуются: «1 день», «2 недели») и текст
|
||
условий. «Применить» закрывает окно и ставит галку — под ней строка
|
||
«Расписание: каждые 14 недель с 15.10.2026, 10:00» со ссылкой
|
||
«Изменить»; выход без применения (крестик, Escape, фон, «Отмена»)
|
||
галку снимает. Заявка создаётся вместе с
|
||
правилом повторения — одной операцией, без отдельной секции в
|
||
проекте. Управление — на странице самой заявки, блок
|
||
«Повторяющаяся заявка»: расписание («каждые 14 дней с 15.10.2026,
|
||
10:00»), ближайший запуск, «Выключить»/«Включить» (выключенное
|
||
правило планировщик пропускает) и «История» (модалка: какие заявки
|
||
создавались по правилу и когда, ссылки на заявки). Мастеру блок
|
||
виден без кнопок. Новая заявка по правилу появляется сама —
|
||
фоновый планировщик сервера бежит раз в сутки, создавая заявку
|
||
**по периоду от этой даты-времени** (точность до суток — выбранное
|
||
время ориентировочное) и **ждёт закрытия прошлой заявки**,
|
||
поэтому дубликатов не будет; клиенту при этом приходит уведомление
|
||
в Telegram, как при обычных напоминаниях.
|
||
12. **Любая роль** → «Настройки» → «Уведомления в Telegram»: заявка,
|
||
пролежавшая в статусе «новая» больше суток, уходит клиенту в Telegram.
|
||
Первым делом — блок «Свой бот»: вставляете токен от @BotFather,
|
||
сервер проверяет его и шифрует, дальше уведомления идут через вашего
|
||
бота (поле `type=password`, токен никогда не показывается обратно —
|
||
только имя бота и кнопка «Отключить бота»). Дальше две цели:
|
||
«Получить код привязки» (одноразовый код и ссылка
|
||
`t.me/<bot>?start=…` → бот привязывает этот чат) и поле
|
||
«Группа или канал» (бот должен состоять в группе). Если на сервере
|
||
нет ни `TELEGRAM_BOT_TOKEN`, ни `DATA_ENCRYPTION_KEY`, экран честно
|
||
пишет, что фича выключена; 400 по токену → «Токен не принят…»,
|
||
400 по цели → «Бот не видит этот чат…», 429 → «Слишком много…».
|
||
|
||
Ошибки API (400/403/409/429) всплывают как есть — их короткий текст
|
||
и есть проверка серверных правил.
|
||
|
||
## Структура
|
||
|
||
```
|
||
Dockerfile прод-образ: nginx:alpine + копия статики и конфига
|
||
compose.yaml nginx-контейнер на :3000 (лимиты: 256m памяти, 0.5 ядра)
|
||
nginx.conf статика + no-cache + rate-limit (10 r/s и 20 соединений
|
||
на IP → 429 сверху) + прокси API-путей на бэкенд
|
||
nginx.prod.conf прод-конфиг: прокси на контейнер api + security-заголовки
|
||
.gitea/workflows/ci.yml CI/CD: node --check, сборка образа, деплой по ручному запуску
|
||
index.html два экрана: вход и приложение
|
||
css/style.css минимум стилей
|
||
js/api.js fetch (BASE='' — тот же origin), хранение сессии, тихий refresh при 401
|
||
js/app.js маршруты в hash, рендер секций, кнопки по ролям; «Настройки»
|
||
— свои боты и привязка Telegram (tgStatus/tgCode/tgSet/tgUnbind/
|
||
tgSetBot/tgDelBot)
|
||
```
|