1. Principii de produs
Directia corecta nu este “formular API”, ci “marketplace de calatorii”: utilizatorul cauta intentia, compara oferte, intelege pretul si face o actiune clara.
- Cautarea trebuie sa fie centrul produsului: destinatie, perioada, persoane, flexibilitate, buget.
- Rezultatele trebuie sa fie scanabile: imagine, titlu, locatie, rating/clasa, masa, nopti, zbor inclus, pret total, CTA.
- Booking-ul nu trebuie blocat daca API-ul nu permite rezervare directa: fallback la cerere de oferta, WhatsApp, telefon, CRM.
- Platforma trebuie sa poata lucra cu mai multe surse: OBS, date locale, oferte manuale, viitoare API-uri de zbor/hotel.
- Tot fluxul trebuie sa fie testabil fara acces OBS real, prin mock/demo data si contract tests.
2. Produsul final
Status implementare curenta: exista un user app testabil pe
http://localhost:3077/?v=5, cu search, filtre, rezultate vizuale, detalii oferta, formular cerere si salvare lead pe server local.| Zona | Ce trebuie sa faca | Rezultat asteptat |
|---|---|---|
| Cautare | Destinatie, perioada, nopti, persoane, copii, buget, masa, categorie, transport. | O lista de oferte relevante in sub 2 secunde dupa cache warm. |
| Rezultate | Sortare, filtre, harta optionala, carduri comparabile, pret total vizibil. | Utilizatorul intelege rapid ce oferta merita deschisa. |
| Detalii oferta | Galerie, locatie, servicii incluse, zbor, camere, masa, reguli, documente. | Pagina suficient de clara pentru decizie fara apel imediat. |
| Booking / cerere | Calculeaza pret, colecteaza turisti, contacte, comentarii, confirma disponibilitate. | Comanda sau lead CRM cu status clar. |
| Backoffice | Vizualizare leaduri, erori API, retry, oferte salvate, conversii. | Managerii Victoria pot lucra fara sa intre in cod. |
3. UX si design
Structura ca Booking/Airbnb
- Primul ecran: bara de cautare compacta, nu formular lung.
- Rezultate in doua coloane pe desktop: filtre in stanga, carduri in centru, sumar/sticky CTA in dreapta doar pe detalii.
- Pe mobil: search sheet, filtre ca bottom sheet, carduri full-width.
- Card oferta: imagine mare, destinatie, hotel/oferta, beneficii, pret total, CTA “Vezi oferta”.
- Filtre: buget, stele/categorie, masa, locatie, transport, flexibilitate date, familie/copii.
- Nu afisam raw API. Payload-ul ramane doar in modul developer.
Design system
- Paleta: alb, gri cald, verde/teal ca accent Victoria Travel, galben discret pentru alerte.
- Componente: SearchBar, DateRangePicker, GuestSelector, FilterDrawer, OfferCard, OfferDetails, BookingPanel, StatusBanner.
- Stari obligatorii: loading skeleton, empty results, API error, demo mode, saved search, expired offer.
- Accesibilitate: contrast, focus visible, navigare din tastatura, texte clare pentru screen reader.
4. Arhitectura recomandata
Frontend
Next.js sau React/Vite cu componente curate, state local pentru search, URL params pentru cautari shareable, SSR/SEO pentru pagini publice.
API Gateway
Server Node care ascunde creditele OBS, normalizeaza raspunsurile, face cache, retry controlat si loguri fara secrete.
Normalizer
Strat unic care transforma OBS, demo data si viitoare surse in acelasi format: Destination, Offer, Room, Package, Price, BookingIntent.
Storage
Postgres/Supabase pentru leaduri, cautari, favorite, erori API, oferte salvate temporar, audit booking.
Backoffice
Dashboard intern pentru leaduri, statusuri, retry, export, comunicare cu clientul si sincronizare CRM.
5. API OBS si integrare
Blocaj curent: contul primit este respins de OBS la login JWT. Platforma locala trebuie sa continue sa functioneze in demo/mock pana primim credite API valide.
- Separare clara intre credentiale test si productie.
- Login JWT server-side, niciodata in HTML public.
- Contract tests pentru endpointurile OBS: login, departure cities, countries, package templates, search, calculate, book.
- Cache pentru liste stabile: orase, tari, pachete, mese, hoteluri.
- TTL scurt pentru disponibilitate si preturi.
- Fallback automat: daca OBS e jos sau respinge auth, produsul intra in demo/internal mode, nu se blocheaza.
- Observabilitate: request id, status code, endpoint, durata, fara token/parola.
6. Booking e2e
| Pas | Actiune utilizator | Actiune sistem |
|---|---|---|
| 1 | Cauta oferta | Normalizeaza criterii si ruleaza search OBS/cache/mock. |
| 2 | Deschide oferta | Verifica disponibilitatea si pastreaza hash-ul/offer id. |
| 3 | Completeaza turisti | Valideaza date, copii, documente si contacte. |
| 4 | Apasa rezervare | Ruleaza calculate, apoi book sau creeaza lead daca booking direct nu e permis. |
| 5 | Primeste confirmare | Email/WhatsApp, status in CRM, task pentru agent. |
7. Testare completa
Niveluri
- Unit tests: normalizatoare, build payload, validari, calcul persoane/copii.
- Contract tests: raspunsuri OBS reale salvate si mockuite, fara tokenuri.
- Integration tests: server + mock OBS + DB test.
- E2E Playwright: cautare, filtre, detalii, booking, eroare OBS, mod demo.
- Visual regression: desktop, tablet, mobil.
- Accessibility checks: focus, contrast, labels, keyboard-only.
Scenarii minime E2E
- Utilizator cauta Chisinau -> Turcia -> Antalya si vede rezultate.
- Utilizator schimba datele si rezultatele se actualizeaza.
- Utilizator aplica filtre de masa si buget.
- Utilizator deschide oferta si vede pret total.
- Utilizator trimite cerere fara booking direct.
- OBS returneaza 401/400 si aplicatia intra in fallback clar.
- Serverul local/OBS cade si UI-ul nu ramane blocat.
8. Roadmap de executie
Sapt. 1
Stabilizare API gateway, demo mode, normalizer, design system initial, layout search/results.
Sapt. 2
Rezultate reale sau mock contract, filtre, sortare, offer details, loading states, mobile UX.
Sapt. 3
Booking request flow, CRM/lead storage, email/WhatsApp handoff, statusuri si dashboard intern.
Sapt. 4
Testare E2E, hardening erori, accesibilitate, performanta, SEO/schema, productie test.
Sapt. 5+
Plati, cont client, favorite, oferte salvate, recomandari, integrare analytics si campanii.
9. Criterii de acceptare
- Search-ul functioneaza e2e cu mock si cu OBS valid.
- Parolele si tokenurile nu apar in HTML, logs, repo sau Obsidian.
- Rezultatele sunt usor de comparat pe mobil si desktop.
- Booking-ul are fallback la lead daca rezervarea directa nu e permisa.
- Minim 15 teste E2E automate trec local si in CI.
- Aplicatia are empty/error/loading states clare.
- Performanta: prima cautare sub 4 secunde, cautari cache sub 2 secunde.
- Designul este coerent, fara formulare brute si fara payloaduri vizibile pentru client.