axe-web/README.md

# 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)
```