# useragent — agent/proxy server (Yii2 Advanced)

## Arxitektura

```
[Android APP] ──(access token + cihaz imzası)──▶ [useragent = bu server] ──(Bearer)──▶ [Billing]
```

App **heç vaxt** birbaşa billing ilə danışmır. Bu server yeganə qapıdır: billing-in ünvanı və
açarı yalnız burada saxlanılır, APK-da olmur.

## Mühit

- Yii2 **Advanced**, kök: `/var/www/html/`
- PHP 8.3, MySQL, baza: `useragent`
- Apache. Domen: `useragent.starttelecom.az` (SSL var)
- Admin panel (backend): daxili `http://10.10.4.143/` — login istifadəçisi: `eminov`
- API: ayrıca `api` tətbiqi (frontend-dən kopyalanıb uyğunlaşdırılıb).
  Təmiz ünvan: `https://useragent.starttelecom.az/api/...` (JSON, CSRF off, stateless)
  Sağlamlıq testi: `GET /api/site/ping` → `{"status":"ok","service":"agent-api",...}`
- Billing eyni lokal şəbəkədədir → daxili IP ilə çağırılır.

## Sabit qaydalar (DƏYİŞMƏZ — razılaşdırılıb)

- **Bir müqavilə = bir cihaz.** Eyni müqavilə başqa cihaza bağlana bilməz.
  (Bir cihazda bir neçə müqavilə — gələcək imkan.)
- Qeydiyyat axını: app açılır → müqavilə nömrəsi → Android key ilə imzalanır → pending →
  təsdiq (nömrə/SMS) → token verilir → cihaz **avtomatik** aktiv olur.
  **Admin paneldə əl ilə təsdiq YOXDUR.**
- Token: **access 10 dəq**, **refresh 30 gün**. Hər şey fonda yenilənir; istifadəçi yalnız ilk
  dəfə təsdiq edir, sonra heç nə basmır.
- **5+ uğursuz cəhd** (müəyyən vaxt ərzində) → cihaz avtomatik **dondurulur**; telefonda
  "X saat dondurulub" göstərilir.
- Bərpa **yalnız adminin işidir** (dondur / blok / aktivləşdir). Bərpada istifadəçi yenidən
  qeydiyyatdan keçmir: tokenlər silinmir, `revoked` olur; admin aktivləşdirəndə fonda bərpa olunur.
- Bildirişlər (təbrik / qəza / profilaktika / kampaniya) → **FCM push**. Push-un içində məlumat
  olmur (yalnız siqnal); app məlumatı sonra bu serverdən çəkir → billing datası Google-dan keçmir.

## Cihaz statusları

`0=pending`, `1=aktiv`, `2=dondurulmuş`, `3=blok`

## Cədvəllər (migration-lar tətbiq olunub)

- `device` — device_uid, platform, public_key, status, last_seen_at, (fcm_token: gələcək)
- `access_token` — type (access/refresh), contract_no, token, expires_at, last_used_at, status
- `registration` — contract_no, full_name, phone_brand/model, verification_code,
  verification_expires_at, verified_at, status, device_id, source_ip
- `request_log` — forensik: ip, source_port, destination_port, x_forwarded_for, user_agent,
  contract_no, created_at, created_at_ms
- `notification`, `notification_delivery`, `failed_attempt`

## Billing API (REAL — mock-u bununla əvəz etmək lazımdır)

- Ünvan: `http://<BILLING_IP>` (daxili LAN). Konfiqurasiyada saxlanır, koda yazılmır.
- Auth: header `Authorization: Bearer <BILLING_TOKEN>`
- Format: JSON, metod: **POST**
- Konfiq: `common/config/params.php` → `token`, `api_host`

Endpointlər (mövcud sayt `starttelecom.az` bunları artıq işlədir — nümunə oradadır):

| Endpoint | Göndərilir | Qaytarır |
|---|---|---|
| `/api/check-contract` | `contract_number`, `phone` (`+` ilə) | `status`, `fullname` |
| `/api/user-service` | `contract_number` | profil/xidmət məlumatı |
| `/api/payments` | `contract_number`, `page`, `per-page` | ödənişlər |
| `/api/complaints` | `contract_number`, `page`, `per-page` | müraciətlər |
| `/api/add-complaint` | `contract_number`, `reason`, `description` | `status` |
| `/api/activity` | `contract_number`, `page`, `per-page` | fəaliyyət |
| `/api/support`, `/api/send-request` | forma sahələri | `status` |

**Qeyd:** `check-contract` müqavilə **+ telefon** tələb edir. Qeydiyyat axınında telefon sahəsi
mütləq olmalıdır (onsuz da təsdiq üçün lazımdır).

**SMS:** SMS API billing tərəfindədir. Mövcud saytda kod frontend-də yaradılır və
`frontend/components/Util.php` → `sendSms()` ilə göndərilir. Agent üçün eyni məntiq qurulacaq.

## Mərhələlər

Bitmiş:
- **D1** — API qurulması, `/api/site/ping` ✓
- **D2** — `POST /api/registration/request` (billing hissəsi hazırda **MOCK**) ✓
- **D3** — `POST /api/registration/verify` ✓
- **D4** — Token sistemi (access + refresh, issue/refresh) ✓
- **D5** — Token yoxlama (auth filtri, `/api/me`) — qurulub
- `FreezeService` (uğursuz cəhd → donma) və telefon uyğunluq yoxlaması yazılıb
- Admin panel: menyu, qeydiyyat siyahısı, cihaz idarəsi

Qalan (prioritet sırası ilə):

1. **KRİTİK BUG — token ləğvi + status yoxlaması.**
   Admin paneldən cihaz/qeydiyyat silinəndə köhnə token hələ **işləməyə davam edir** →
   "bir müqavilə = bir cihaz" qaydası pozulur. Eyni müqavilə iki telefonda eyni anda işləyir.
   Həll: hər sorğuda token + cihaz statusu yoxlanmalı; silinmə/dondurma zamanı tokenlər
   `revoked` olmalı. **Təhlükəsizlik məsələsidir, ən vacibidir.**

2. **D9 — real billing** (`BillingService`-dəki mock → real API çağırışı).
   `common/services/BillingService.php` içindəki `findSubscriber()` mock data qaytarır.
   Real: yuxarıdakı cədvəldəki endpointlərə `yii\httpclient\Client` ilə POST + Bearer.
   Nümunə kod: mövcud saytın `frontend/controllers/SiteController.php` faylında.

3. **D6** — forensik loglama (`request_log` doldurulması)
4. **D7** — 5+ uğursuz cəhd → avtomatik donma (tamamlanması)
5. **D8** — admin paneldə cihaz status düymələri (dondur/blok/aktivləşdir)
6. **Maintenance Mode** — server "bağlıdır" siqnalı; app onu göstərir
7. **Feature Flag** — funksiyaları uzaqdan aç/bağla
8. **D10** — FCM push (`device.fcm_token` sahəsi əlavə olunmalı)

## Android app (ayrı layihə)

- Paket: `az.starttelecom.app`, Kotlin + Jetpack Compose, minSdk 24
- 4 ekran hazırdır (Profil, Ödənişlər, Tariflər, Müraciətlər) — hələ **sabit (hardcoded) data** ilə
- Şəbəkə qatı hələ YOXDUR. Sonra: Retrofit → bu serverin API-si
- Gözləyən işlər: çoxdillilik (AZ/RU/EN, `strings.xml`), şəbəkə xətası ekranı
  ("Serverlə əlaqə yoxdur / Yenidən cəhd et"), maintenance ekranı, real data

## Təhlükəsizlik qeydləri

- Billing tokeni və SMS parolu **konfiqurasiyada** saxlanır, koda yazılmır, repo-ya düşmür.
- Bu açarlar bir dəfə açıq kanalda görünüb → **rotasiya edilməlidir** (yeni token yaradılsın,
  köhnəsi ləğv olunsun; SMS parolu dəyişdirilsin).
- `debug_code` (təsdiq kodunun cavabda qaytarılması) yalnız mock/test üçündür —
  real billing qoşulanda **çıxarılmalıdır**.

## İş üsulu

- Addım-addım gedirik. Hər mərhələ bitəndə test edilir (adətən `curl` ilə), sonra növbətiyə keçilir.
- Kod və izahlar **Azərbaycan dilində**.
- Qısa, konkret cavablar; artıq izahat yox.