# SMM Panel — Raporti i ndërtimit

Ndërtuar nga e para si një panel i plotë SMM (panel klienti + panel admini) me **followers99.com**
si provider real, sipas specifikimit të dhënë. Të katër fazat u ndërtuan, kaluan `npx tsc --noEmit`
dhe `npm run build`, dhe u bënë commit veç e veç.

**Stack:** Next.js 15.5 (App Router) · TypeScript strict · Tailwind v4 · shadcn/ui · PostgreSQL ·
Prisma 6 · Auth.js (NextAuth v5) · Zod 4 · recharts · lucide-react · date-fns · node-cron ·
decimal.js. Pa Redis, pa BullMQ, pa teste (sipas kërkesës).

---

## 1. Si ta nis projektin

### Parakushtet
- Node.js 22+ dhe npm (të instaluara).
- PostgreSQL. **Në këtë server docker/podman nuk ekzistojnë**, prandaj u ngrit një PostgreSQL 13
  lokal që projekti e përdor tashmë (shih §5.a). Për çdo mjedis tjetër përdor `docker-compose.yml`.

### Hapat (mjedisi aktual — DB tashmë duke punuar)
```bash
cd /home/blenard/getfollowers.ai

# 1. Varësitë (nëse s'janë instaluar)
npm install

# 2. Baza e të dhënave është ngritur tashmë në 127.0.0.1:55432 (shih §5.a).
#    Nëse është ndalur, rinise:
pg_ctl -D /home/blenard/pgdata-smm \
  -o "-p 55432 -c listen_addresses=127.0.0.1 -c unix_socket_directories=/home/blenard/pgdata-smm" \
  -l /home/blenard/pgdata-smm/server.log start

# 3. Migrimet + seed (skema tashmë e migruar dhe e mbushur; riekzekuto sipas nevojës)
npx prisma migrate deploy
npm run db:seed          # idempotent — mund të riekzekutohet pa problem

# 4. Aplikacioni
npm run dev              # zhvillim, http://localhost:3000
# ose
npm run build && npm start   # prodhim

# 5. Worker-i i jobs (proces i veçantë, në një terminal tjetër)
npm run worker
```

### Hapat në një mjedis tjetër (me Docker)
```bash
docker compose up -d               # ngre Postgres 16 në portën 55432
# përditëso DATABASE_URL në .env nëse ndryshon fjalëkalimi/hosti
npx prisma migrate deploy && npm run db:seed
npm run build && npm start
npm run worker
```

Jobs-et mund të nisen edhe manualisht pa worker-in, përmes një route të mbrojtur me sekret:
```
POST /api/cron/<job>?secret=<CRON_SECRET>
```
ku `<job>` ∈ `dispatch, sync, prices, dripfeed, subscriptions, provider-balance, refill-cancel`.

---

## 2. Kredencialet

| Roli  | Username | Password  | Shënim |
|-------|----------|-----------|--------|
| Admin | `admin`  | `admin123` | akses te `/admin` |
| User  | `user`   | `user123`  | bilanc fillestar $500, ka API key |

Ekzistojnë edhe ~11 përdorues demo me statuse/bilance të ndryshme (të gjithë me fjalëkalim të
hash-uar). Login: `/signin` · Paneli i klientit: `/` · Paneli i adminit: `/admin`.

---

## 3. Çelësi i followers99 dhe sandbox → live

Sekretet janë në `.env` (i gjeneruar automatikisht; `.env.example` mbahet në git me vlera bosh).

```env
PROVIDER_FOLLOWERS99_URL="https://followers99.com/api/v2"
PROVIDER_FOLLOWERS99_KEY=""        # <-- vendos këtu çelësin tënd real
PROVIDER_MODE="sandbox"            # sandbox | live
```

**Për të kaluar në prodhim me followers99:**
1. Vendos çelësin te `PROVIDER_FOLLOWERS99_KEY` në `.env`. (Seed-i e enkripton dhe e ruan te
   tabela `Provider`; çelësi enkriptohet me AES-256-GCM dhe **nuk kthehet kurrë te frontend-i**.)
   Alternativë nga UI: **Admin → Settings → Providers → Edit** — fusha e API key është
   "write-only" (shfaqet vetëm i maskuar).
2. Ndrysho `PROVIDER_MODE="live"`.
3. Rinise aplikacionin dhe worker-in.

Në `sandbox` (default), asnjë thirrje reale nuk bëhet: `add` kthen ID fals, `status` e çon porosinë
Pending → In progress → Completed/Partial me kalimin e kohës, `balance` kthen 500, `services` kthen
~56 shërbime demo. Kjo lejon testimin e plotë pa çelës real dhe pa shpenzuar para.

---

## 4. Çfarë u ndërtua (checklist)

### Faza 1 — Baza ✅
- ✅ Skeleti Next.js 15 + TS + Tailwind v4 + shadcn/ui (61 komponentë)
- ✅ Skema e plotë Prisma: 27 modele, 19 enume, të gjitha fushat e specifikimit + 2 modele shtesë
  (`VerificationCode`, `JobRun`); para gjithmonë `Decimal(20,5)`
- ✅ Migrimi i aplikuar; `docker-compose.yml` për portabilitet
- ✅ Auth.js v5 (credentials username/email + bcrypt), signup/login/logout, forgot/reset password
  (token në DB, email në console), 2FA me email opsionale, middleware për mbrojtjen e rrugëve,
  `SignInLog` në çdo hyrje
- ✅ `applyTransaction` — i vetmi shkrues i `User.balance` (row lock, Decimal, `balanceAfter`)
- ✅ Klienti i providerit `lib/providers/followers99.ts` (POST form-urlencoded, timeout 30s, 3
  retry vetëm për rrjet/5xx, kurrë retry për `add`) + klienti sandbox + rregullat mbrojtëse
  (kurrë nën kosto, kontroll bilanci para dispatch, idempotencë, enkriptim çelësi)
- ✅ Seed: admin/user, provideri, 8 kategori, 58 shërbime (të 10 tipet), 66 porosi historike,
  16 pagesa, 5 tiketa, 3 drip-feed, 3 subscriptions, 4 metoda pagese, settings

### Faza 2 — Paneli i klientit ✅
- ✅ Layout me sidebar navy + header me bilancin + dark/light + drawer në mobile (pa Child Panel)
- ✅ `/` New order (3 kartela, filtra platformash, fusha dinamike sipas tipit të shërbimit,
  charge live, drip-feed, deep-link `?service=ID`)
- ✅ `/orders` (tabs, paginim server-side, Refill/Cancel), `/orders/refunds`, `/refill`
- ✅ `/services` (publik + i loguar, Favorite, modal përshkrimi), `/updates`
- ✅ `/addfunds` (metoda + instruksione HTML + histori + FEE/BONUS; fraud flags; webhook stubs
  Cryptomus/PayPal me TODO), `/account` (profil, siguri, 2FA, API key)
- ✅ `/drip-feed`, `/subscriptions`, `/massorder`, `/tickets` + `/tickets/[id]`, `/affiliates`
- ✅ `/api` (dokumentim i API-së sonë), `/terms`, `/ref/[code]` (cookie referral)
- ✅ Landing page publike (hero, statistika live nga DB, "si funksionon", shërbime popullore, FAQ)

### Faza 3 — API v2 + jobs ✅
- ✅ `POST /api/v2` (auth me API key, form-urlencoded + JSON, të 7 veprimet 1:1 me standardin,
  të 10 variantet e `add`, rate limit 120/min për çelës, mesazhe gabimi standarde)
- ✅ 7 jobs me node-cron + `worker.ts` + `/api/cron/[job]`: dispatch (30s), sync (2min, rimbursime
  proporcionale), prices (ditore), dripfeed (1min), subscriptions (5min), provider-balance (15min),
  refill-cancel (5min); secili me lock, `JobRun` log, alarm pas 3 dështimeve
- ✅ **Të 7 jobs u ekzekutuan një herë me sukses (smoke run)** dhe API v2 u testua me të 10 variantet
  e `add` deri te dispatch-i — pa dublim pagese për subscriptions/drip-feed

### Faza 4 — Paneli i adminit ✅
- ✅ Layout me nav horizontal navy + badge detyrash + alarme + dark mode
- ✅ `<AdminTable>` i vetëm (sortim, filtra, kërkim, zgjedhje masive, "Show totals", "Export CSV")
  përdorur në çdo faqe
- ✅ Users (edit, funds, discount, custom rates, sign-in history, same-IP, suspend, login-as-user)
- ✅ Orders (tabs, filtra, profit, Details, Change status, Set partial, Cancel & refund, Resend)
- ✅ Services (Add/Import nga provideri me markup, Sync prices, drag-alternativë me shigjeta, bulk)
- ✅ Payments (Add, confirm/reject, fraud risk, FEE), Tickets (chat, canned, assignee)
- ✅ Refill, Cancel, Subscriptions, Drip-feed (me run log), Updates
- ✅ Affiliates (Referrals/Payouts + aprovim), Reports (6 tabs, Chart/Table, CSV, profit = charge−cost)
- ✅ Settings (General, Providers, Payments, Modules, Notifications, Audit log)
- ✅ Audit log për çdo veprim admin që prek para/çmime/statuse/settings

---

## 5. Vendime që mora vetë

**a) Baza e të dhënave — PostgreSQL lokal në vend të Docker-it.** Docker dhe podman nuk ekzistojnë
në këtë server. Sipas zinxhirit të fallback-ut në specifikim, në vend që të bija te SQLite (që humbet
`Decimal`, `citext` dhe sjelljen reale të prodhimit), ngrita një **PostgreSQL 13 të vërtetë**, në
pronësi tonën, në `127.0.0.1:55432` (data dir `/home/blenard/pgdata-smm`, user `smm`, db `smm_panel`,
fjalëkalim i gjeneruar). `docker-compose.yml` (Postgres 16) mbetet për mjedise të tjera. Postgres-i i
sistemit në portën 5432 nuk u prek.

**b) Skedarët e cPanel** (`.htaccess`, `php.ini`, `.user.ini`, `.well-known/`) u lanë në vend por
u shtuan te `.gitignore` — s'janë pjesë e aplikacionit Next.js.

**c) Dy modele shtesë** që specifikimi s'i listoi por rrjedha i kërkon: `VerificationCode`
(reset password / 2FA / email confirm) dhe `JobRun` (log ekzekutimi jobs-esh). Disa fusha shtesë te
`User` (`twoFactorEnabled`, `allowedPaymentMethods`, `hiddenServices`), `Order` (`subscriptionId`),
`Refill`/`CancelTask` (`reason`) për funksionalitetin e adminit. Enume të pa-tipizuara: `DripFeedStatus`,
`PayoutStatus`.

**d) `Service.id` dhe `Order.id` janë `Int autoincrement`** (ID publike numerike, standard i industrisë),
gjithçka tjetër `cuid`.

**e) Mapimi i statuseve në API v2:** standardi ekspozon 6 fjalë; statuset e brendshme kolapsojnë —
`AWAITING` dhe `ERROR` → "Pending" (asnjëri final), `FAIL` (final, i rimbursuar) → "Canceled".

**f) Subscriptions ngarkohen paraprakisht** për `maxQuantity × (posts + oldPosts)`; job-i krijon
porosi-fëmijë me charge 0 nga ky buxhet (kurrë s'thërret `createOrder` dy herë). Drip-feed njësoj:
prindi mban charge-un, fëmijët kanë charge 0 — raportet e fitimit i përjashtojnë fëmijët.

**g) Renditja e shërbimeve/metodave me shigjeta ↑↓** në vend të drag & drop, për të mos shtuar një
varësi të re.

**h) Header/footer code te General settings** ruhet por nuk injektohet ende në layout (shih §6).

**i) Riparim i një bug-u real (Faza 3, smoke run):** klienti sandbox nxirrte gabimisht tipin
"Default" për shërbimet e seed-it, duke bërë të dështonin (dhe rimbursoheshin) porositë PACKAGE /
CUSTOM_COMMENTS / MENTIONS në modalitetin default. U shtua `inferTypeFromParams()` — u verifikua që
tani dispatch-i i dërgon saktë.

---

## 6. Probleme të njohura

- **E paverifikuar në runtime nga UI:** sipas rregullave (pa dev server, pa teste), UI-ja dhe server
  actions janë verifikuar vetëm me `tsc` + `build`. Logjika e parave dhe jobs-et **u testuan në
  runtime** me smoke-run në Fazën 3. Faqet e adminit janë compile-verified.
- **Cryptomus / PayPal:** vetëm struktura (webhook routes me TODO + verifikim nënshkrimi); pagesat
  krijohen PENDING dhe i konfirmon admini manualisht. Integrimi real mbetet për hapat e ardhshëm.
- **Emailet:** vetëm `console.log` (pa SMTP, sipas kërkesës) — reset link, 2FA code, email confirm.
- **Header/footer code** te settings ruhet por nuk renderohet ende në layout.
- **Refill window** matet nga `Order.updatedAt` (skema s'ka `completedAt`); çdo shkrim i mëvonshëm te
  porosia e zhvendos dritaren. Zgjidhje: shto `Order.completedAt` në një migrim të ardhshëm.
- **Alarmet e adminit** ruhen në një rresht të vetëm `Setting` JSON — dy `pushAlert` në të njëjtin çast
  mund të mbishkruajnë njëri-tjetrin (pranueshëm për worker single-instance).
- **Rate limit i API v2** është in-memory (single-instance); për shumë instanca duhet Redis.
- **Sandbox** ruan gjendjen në memorie — rinisja e worker-it e rivendos; porositë e vjetra bien te një
  progresion id-hash (realist, por remains i vogël).
- `npm audit` raporton disa paralajmërime në varësitë tranzitive të `create-next-app`/eslint — të palëna
  qëllimisht (fix-i do të bënte downgrade major-esh). Build-i emeton 2 warning nga `jose`/next-auth
  (Edge Runtime CompressionStream) — të padëmshme.
- Disa kufij UI: service pickers të kapur (300/200 rreshta me kërkim), child orders në detaje të kapur
  në 200, "same IP" të kapur në 1000 rreshta.

---

## 7. Hapat e ardhshëm

1. **Pagesat reale:** përfundo webhook-et Cryptomus/PayPal (verifikim nënshkrimi + kreditim përmes
   `applyTransaction`), shto një gateway karte nëse duhet.
2. **Email real:** lidh një SMTP/provider (Resend, Postmark) për reset password, 2FA, konfirmime,
   njoftime — kodi i emaileve tashmë ekziston, thjesht zëvendëso `console.log`.
3. **Live me followers99:** vendos çelësin real, `PROVIDER_MODE=live`, monitoro dispatch/sync.
4. **Deploy:** ndër opsione — një VPS me Postgres + PM2 (një proces për `next start`, një për
   `npm run worker`) + reverse proxy, ose një platformë me DB të menaxhuar. Skedarët cPanel sugjerojnë
   hosting të përbashkët — Next.js kërkon Node runtime, jo PHP.
5. **Provider-a shtesë:** arkitektura e pranon tashmë (tabela `Provider`, klient i abstraktuar) — shto
   një klient të ri te `lib/providers/` dhe një rresht te tabela.
6. **Migrim i vogël i rekomanduar:** shto `Order.completedAt` për dritaren e saktë të refill-it.
7. **Prodhim:** Redis për rate-limit + lock jobs nëse skalohet në shumë instanca; email/SMS për 2FA
   real; monitorim (Sentry/PostHog).

---

## Struktura e projektit
Kontrata e plotë e arkitekturës (konvencionet që ndoqën të gjithë agjentët gjatë ndërtimit) është te
`docs/ARCHITECTURE.md`. Rrugët kryesore: `app/` (faqet), `lib/` (logjika: `ledger`, `pricing`,
`orders`, `providers/`, `jobs/`, `actions/`, `admin/`), `prisma/` (skema + seed), `worker.ts` (jobs).