# Особистий кабінет абонента (водоканал)

Веб-кабінет для абонентів водоканалу: вхід за номером телефону, перегляд
особових рахунків, балансу, нарахувань, історії платежів і передача показань
лічильників. Дані беруться з бази **1С** («Облік в ОСББ / розрахунки
квартплати в Україні») через **власний HTTP-сервіс `Cabinet`**, який
публікується у вашій 1С (код і інструкція — у [`onec-1c/`](onec-1c/)).
Кабінет повністю ваш і не залежить від сторонніх сервісів.

> Детальний розбір конфігурації 1С і схема інтеграції —
> [`docs/1c-analiz-konfiguratsii.md`](docs/1c-analiz-konfiguratsii.md).
> 1С-сторона (HTTP-сервіс) — [`onec-1c/README.md`](onec-1c/README.md).

## Можливості

- **Вхід за номером телефону** + пароль. Оператор видає абоненту тимчасовий
  пароль (панель `/admin.html`); при першому вході система вимагає встановити
  постійний.
- Один номер → **декілька особових рахунків** (пошук і перевірка по номеру).
- Перегляд **балансу/боргу**, **нарахувань**, **історії платежів**,
  **лічильників**.
- **Передача показань** лічильників (запис у 1С, регістр
  `ПоказанияПриборовУчетаССайта`).
- Два режими роботи: `demo` (тестові дані, без 1С) та `gkh` (реальна 1С).

## Технології

Python 3.11 · FastAPI · SQLAlchemy · PostgreSQL (або SQLite для демо) ·
JWT · bcrypt · vanilla-JS фронтенд.

## Швидкий старт (демо-режим)

```bash
cd backend
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env            # за потреби відредагуйте
uvicorn app.main:app --reload   # http://127.0.0.1:8000
```

- Кабінет абонента: <http://127.0.0.1:8000/>
- Панель оператора: <http://127.0.0.1:8000/admin.html>
  (демо-логін: `operator` / `operator`)
- Документація API (Swagger): <http://127.0.0.1:8000/docs>

### Демо-сценарій

1. Відкрийте `/admin.html`, увійдіть як `operator`/`operator`.
2. Видайте тимчасовий пароль для номера **`0671112233`** (2 рахунки) або
   **`0509998877`** (1 рахунок).
3. Відкрийте `/`, увійдіть цим номером і тимчасовим паролем.
4. Встановіть постійний пароль → перегляньте рахунки, баланс, платежі,
   передайте показання.

## Перемикання на реальну 1С

Спочатку опублікуйте власний HTTP-сервіс `Cabinet` у 1С — код та покрокова
інструкція у [`onec-1c/README.md`](onec-1c/README.md). Потім у `.env`:

```
ONEC_MODE=http
ONEC_HTTP_BASE_URL=https://<хост-1С>/<база>/hs/cabinet
ONEC_HTTP_USERNAME=<службовий користувач 1С>
ONEC_HTTP_PASSWORD=<пароль>
```

Обов'язково: HTTPS на веб-сервері 1С і доступ до сервісу **лише з IP сервера
кабінету** (фаєрвол/VPN). Перевірте також заповненість телефонів у
`ЛицевыеСчета` (`МобТелефон`/`Телефон`).

## Тести

```bash
cd backend
source .venv/bin/activate
pip install -r requirements.txt
python -m pytest -q
```

## Структура

```
backend/
  app/
    main.py            точка входу FastAPI
    config.py          налаштування (.env)
    phone.py           нормалізація номерів телефону
    db.py, models.py   БД кабінету (користувачі, аудит)
    security.py        паролі (bcrypt), JWT, тимчасові паролі
    services.py        індекс «телефон → особові рахунки»
    routers/           auth, accounts, meters, admin
    onec/              інтеграція з 1С
      base.py          контракт клієнта
      http1c.py        реальний клієнт власного HTTP-сервісу 1С (JSON)
      demo.py          демо-дані
      mapping.py       сирі рядки → обʼєкти API
  tests/               end-to-end тести
frontend/              кабінет абонента + панель оператора
onec-1c/               1С-сторона: код HTTP-сервісу Cabinet + інструкція
docs/                  аналіз конфігурації 1С
```

## Безпека

- Абоненти **ніколи** не звертаються до 1С напряму — лише бекенд кабінету
  (server-to-server, Basic Auth). Облікові дані 1С тримайте у `.env`/секретах.
- Паролі зберігаються хешем (bcrypt). Токени — JWT з обмеженим терміном.
- Ідентичність привʼязана до номера телефону: оператор має голосом
  підтвердити особу перед видачею тимчасового пароля.
- Для проду обовʼязково задайте власний `SECRET_KEY`, `ADMIN_PASSWORD`,
  увімкніть HTTPS і бажано обмежте доступ до `/admin.html`.