# RingRing - architektura MVP call trackingu

## Cel

RingRing ma mierzyc telefony jako konwersje dla klientow obslugiwanych w Ads. MVP nie probuje byc pelnym Ringostatem. Ma pokazac dzialajacy przeplyw:

1. Wejscie z reklamy z `gclid`, `gbraid`, `wbraid` albo parametrami social.
2. Dynamiczna podmiana numeru telefonu na stronie klienta.
3. Zapis wizyty, numeru i atrybucji.
4. Zapis połączenia z webhooka operatora telefonii albo symulatora.
5. Kwalifikacja połączenia jako konwersji.
6. Eksport payloadu do Google Ads.

## Warstwy systemu

### 1. Skrypt na stronie klienta

Plik `static/tracker.js` jest odpowiednikiem wklejki instalowanej u klienta.

Robi trzy rzeczy:

- generuje i trzyma `visitor_id` w `localStorage`,
- wysyla do backendu aktualny URL, referrer i ID klienta,
- podmienia kazdy element `[data-ringring-phone]` lub `.rr-phone` na przypisany numer.

Docelowo ten plik powinien isc z CDN, np. `https://cdn.twojadomena.pl/tracker.js`.

### 2. Backend trackingowy

`server.py` wystawia endpointy:

- `POST /api/track` - zapis wizyty i wybor numeru,
- `POST /api/simulate-call` - lokalny symulator połączenia,
- `POST /api/webhooks/twilio/call-status` - szkic webhooka operatora,
- `POST /api/export/google-ads` - eksport konwersji,
- `GET /api/state` - dane do panelu.

Na demo uzywa SQLite. Produkcyjnie te same tabele powinny przejsc do PostgreSQL.

### 3. Telefonia

Produkcyjnie potrzebny jest operator CPaaS/SIP, np. Twilio, Vonage, MessageBird, Zadarma, Daktela albo lokalny operator SIP.

Minimalny przeplyw:

1. Kupujesz pule numerow.
2. Kazdy numer przekierowuje rozmowe na numer klienta.
3. Operator wysyla webhook z `from`, `to`, `duration`, `status`, `recording_url`.
4. Backend laczy `to` z numerem trackingowym i ostatnia wizyta.
5. Połączenie powyzej progu, np. 60 sekund, staje sie konwersja.

### 4. Eksporter reklamowy

W MVP aktywny jest Google Ads. Kod buduje dwa warianty:

- `click_conversion`, gdy mamy `gclid`, `gbraid` albo `wbraid`,
- `call_conversion`, gdy brakuje click ID, ale mamy `caller_id` i czas startu rozmowy.

Sociale powinny wejsc jako adaptery po Google Ads:

- Meta Conversions API: `fbclid`/`fbc`, `fbp`, `event_name`, `event_time`, `event_id`, opcjonalnie zahashowany telefon.
- TikTok Events API: `ttclid`, `event`, `timestamp`, `context`.
- LinkedIn Conversions API: `li_fat_id`, conversion rule, timestamp.

## Model danych

Najwazniejsze encje:

- `clients` - klient, waluta, numer docelowy, conversion action Google Ads,
- `tracking_numbers` - pule numerow per kanal,
- `visits` - wejscia z kampanii i click ID,
- `calls` - rozmowy, kwalifikacja, wartosc, status eksportu.

## Decyzje techniczne

Startujemy od Google Ads, bo to daje najwieksza wartosc dla kampanii Search i PMax. Social media warto zaprojektowac od razu w danych, ale nie trzeba ich uploadowac w pierwszej wersji. W tym demo `fbclid`, `ttclid` i `li_fat_id` sa juz zapisywane, wiec pozniejszy adapter nie wymaga zmiany wklejki.

Najwazniejsze ograniczenie: numerow musi byc wystarczajaco duzo dla ruchu. Dla malego klienta moze wystarczyc numer per kanal. Dla wiekszego ruchu potrzebna jest dynamiczna pula numerow z czasem rezerwacji, np. numer przypisany do sesji na 30-60 minut.

## Produkcyjna infrastruktura

Minimalna wersja:

- VPS albo mały cloud app server,
- PostgreSQL,
- domena i SSL,
- webhooki od operatora telefonii,
- cron/job do ponawiania eksportow,
- logi i alerty,
- kopie bazy.

Wersja docelowa:

- osobny worker do eksportow,
- kolejka zadan,
- panel multi-client,
- role uzytkownikow,
- audyt zmian,
- retencja danych,
- zgody i polityka prywatnosci.

## Prywatnosc i compliance

Call tracking dotyka danych osobowych: numer telefonu dzwoniacego, nagranie, a czasem transkrypcja. Produkcyjnie trzeba miec:

- umowe powierzenia z operatorem telefonii,
- polityke retencji danych,
- maskowanie lub hashowanie danych przy eksporcie tam, gdzie platforma tego wymaga,
- zgody i podstawe prawna na nagrywanie rozmow,
- konfiguracje consent mode / zgody marketingowej dla danych reklamowych.