BizOne-portal/docs/CODEX_HANDOFF.md

# Codex Handoff

Snapshot tanggal: `2026-05-22`

Dokumen ini adalah ringkasan kondisi terakhir BizOne Portal supaya sesi Codex berikutnya bisa lanjut tanpa bongkar ulang dari nol.

## Ringkasan Cepat

- Repo lokal: `/home/wira/work/codex/BizOne-portal`
- Repo server: `/srv/bizone-web`
- Branch: `main`
- Domain production: `https://portal.bizone.id`
- Backend production: `127.0.0.1:3001` via systemd `bizone-backend`
- Frontend production: `127.0.0.1:3000` via systemd `bizone-frontend`
- Meta webhook URL: `https://portal.bizone.id/api/webhooks/whatsapp`
- Midtrans notification URL: `https://portal.bizone.id/api/wallet/midtrans/notification`

## Commit Terakhir Lokal

```text
cc819ad Accept Midtrans dashboard notification tests
96b326e Fix roles page locale label typing
5144207 Prepare BizOne portal production wallet and UI
36be860 Add Codex handoff and update public assets
46ea32c Refresh session in contacts API proxy routes
```

Catatan penting:

- Push dari environment Codex lokal gagal karena remote HTTPS butuh credential interaktif.
- User perlu menjalankan `git push origin main` dari terminal interaktif yang punya akses Git.
- Server sudah pernah melihat commit `96b326e`, tapi commit `cc819ad` perlu dipastikan sudah masuk remote/server sebelum test ulang Midtrans dashboard.

## Status Git Auth

Remote saat terakhir dicek:

```text
origin https://git.iptek.co/wirabasalamah/BizOne-portal.git
```

Push dari Codex gagal dengan:

```text
fatal: could not read Username for 'https://git.iptek.co': No such device or address
```

Solusi user:

```bash
cd /home/wira/work/codex/BizOne-portal
git push origin main
```

Atau pakai username:

```bash
git push https://wira.irawan%40gmail.com@git.iptek.co/wirabasalamah/BizOne-portal.git main
```

Jangan taruh token di command kalau tidak perlu, karena bisa masuk shell history.

## Fitur Besar Yang Sudah Masuk

- Redesign login, dashboard shell, sidebar, card spacing, dan halaman utama dashboard.
- Dual bahasa `EN/ID` diperluas ke banyak halaman.
- Global search di header.
- Notification center di header.
- Help page dari icon `?`.
- Profile menu dan halaman profile user.
- Wallet/saldo untuk broadcast.
- Minimum top up `Rp50.000`.
- Preset top up `50rb`, `100rb`, `250rb`, `500rb`, `1jt`.
- Harga broadcast sementara `Rp500` per pesan.
- Broadcast hanya cek saldo sebelum kirim, saldo dipotong setelah worker memproses pesan sukses.
- Integrasi Midtrans Snap API awal.
- Midtrans payment methods: `gopay`, `shopeepay`, `bank_transfer`, `credit_card`.
- Midtrans notification webhook.
- Production deploy docs untuk `portal.bizone.id`.
- Root `/` redirect ke `/login`, tidak lagi menampilkan starter landing page.

## Midtrans Status Terakhir

URL final yang harus dipakai di dashboard Midtrans:

```text
https://portal.bizone.id/api/wallet/midtrans/notification
```

Server internal test sudah pernah menghasilkan response ini setelah route aktif:

```json
{"message":"Invalid Midtrans notification signature.","error":"Bad Request","statusCode":400}
```

Itu normal untuk payload kosong.

Dashboard Midtrans test notification mengirim payload seperti:

```json
{
  "transaction_status": "settlement",
  "status_code": "200",
  "signature_key": "...",
  "payment_type": "gopay",
  "order_id": "payment_notif_test_G311975080_...",
  "merchant_id": "G311975080",
  "gross_amount": "105000.00"
}
```

Karena `order_id` test tidak ada di tabel `payment_orders`, backend awalnya menolak. Commit `cc819ad` memperbaiki ini:

- Signature tetap divalidasi.
- Kalau `order_id` diawali `payment_notif_test_` dan `merchant_id` cocok dengan `MIDTRANS_MERCHANT_ID`, backend return `200`.
- Transaksi asli tetap wajib punya payment order.

Setelah commit `cc819ad` dipull ke server, jalankan:

```bash
cd /srv/bizone-web

git pull

set -a
source .env
set +a

cd backend
NODE_ENV=development npm ci
npm run db:generate
npm run build
npm run db:migrate:deploy
sudo systemctl restart bizone-backend
```

Lalu test:

```bash
curl -i -X POST https://portal.bizone.id/api/wallet/midtrans/notification \
  -H "Content-Type: application/json" \
  -d '{}'
```

Payload kosong boleh tetap `400 Invalid Midtrans notification signature`; test dashboard Midtrans yang signed harus `200` setelah commit `cc819ad` aktif di server.

## Midtrans Env Production/Server

User menunjukkan dashboard Midtrans `Environment Sandbox`, tapi key formatnya tetap:

```text
Mid-client-...
Mid-server-...
```

Jadi jangan lagi mengasumsikan sandbox pasti `SB-Mid-*` untuk akun ini. Yang penting key di `/srv/bizone-web/.env` sama dengan dashboard Midtrans yang dipakai.

Contoh env server saat terakhir dibahas:

```dotenv
MIDTRANS_ENV=sandbox
MIDTRANS_SERVER_KEY=Mid-server-...
MIDTRANS_CLIENT_KEY=Mid-client-...
MIDTRANS_MERCHANT_ID=G311975080
MIDTRANS_ALLOWED_PAYMENT_TYPES=gopay,shopeepay,bank_transfer,credit_card
```

Jangan commit `.env`.

## Server Deploy Notes

Jika backend build gagal dengan:

```text
sh: 1: tsc: not found
```

Penyebab: `NODE_ENV=production npm ci` tidak memasang devDependencies. Pakai:

```bash
NODE_ENV=development npm ci
```

Jika backend build gagal dengan banyak error Prisma seperti:

```text
Property 'sql' does not exist on type 'typeof Prisma'
Module '@prisma/client' has no exported member 'Campaign'
```

Penyebab: Prisma client stale setelah `npm ci`. Urutan benar:

```bash
cd /srv/bizone-web
npm install

cd backend
NODE_ENV=development npm ci
npm run db:generate
npm run build
```

Setelah build:

```bash
npm run db:migrate:deploy
sudo systemctl restart bizone-backend
```

Cek route wallet:

```bash
sudo journalctl -u bizone-backend -n 200 --no-pager | grep -i wallet
```

Harus ada:

```text
WalletController {/api/wallet}
Mapped {/api/wallet/topups/midtrans, POST}
WalletMidtransWebhookController {/api/wallet/midtrans}
Mapped {/api/wallet/midtrans/notification, POST}
```

## Nginx Production

Config nginx yang user kirim sudah benar untuk Midtrans dan Meta:

```nginx
location /api/webhooks/ {
    proxy_pass http://127.0.0.1:3001/api/webhooks/;
}

location /api/wallet/midtrans/ {
    proxy_pass http://127.0.0.1:3001/api/wallet/midtrans/;
}

location /backend-api/ {
    proxy_pass http://127.0.0.1:3001/api/;
}

location / {
    proxy_pass http://127.0.0.1:3000;
}
```

Kalau public endpoint `502`, cek backend/frontend service. Kalau internal backend `404`, berarti backend build belum memuat route baru.

## Credential Dev/Admin

Default seed admin:

```text
Email: admin@bizone.id
Password: ChangeMe123!
```

Jika server login gagal, reset seed:

```bash
cd /srv/bizone-web/backend
set -a
source ../.env
set +a
npm run seed:admin
```

Setelah production login pertama, ganti password dan aktifkan 2FA.

## Files Penting Yang Diubah

Backend:

- `backend/src/wallet/*`
- `backend/src/app.module.ts`
- `backend/src/campaigns/campaigns.service.ts`
- `backend/src/campaigns/campaigns.controller.ts`
- `backend/src/common/permission.guard.ts`
- `backend/src/auth/*`
- `prisma/schema.prisma`
- `prisma/migrations/0015_wallet/migration.sql`

Frontend:

- `frontend/src/app/dashboard/wallet/page.tsx`
- `frontend/src/components/wallet-topup-form.tsx`
- `frontend/src/components/dashboard-shell.tsx`
- `frontend/src/components/global-search-button.tsx`
- `frontend/src/components/notification-center.tsx`
- `frontend/src/components/profile-menu.tsx`
- `frontend/src/components/profile-forms.tsx`
- `frontend/src/app/dashboard/help/page.tsx`
- `frontend/src/app/dashboard/profile/page.tsx`
- `frontend/src/app/page.tsx`
- `frontend/src/app/globals.css`
- banyak halaman dashboard untuk spacing dan dual bahasa.

Deploy docs:

- `deploy/debian12/app.env.example`
- `deploy/debian12/nginx.portal.bizone.id.conf`
- `deploy/debian12/README.md`
- `PRODUCTION_CHECKLIST.md`
- `PRODUCTION_READINESS.md`
- `docs/production-server-checklist.md`

## Next Steps Paling Dekat

1. Push commit `cc819ad` ke remote.
2. Pull di server.
3. Rebuild backend dengan urutan Prisma yang benar.
4. Restart `bizone-backend`.
5. Test ulang Midtrans notification URL dari dashboard Midtrans.
6. Rebuild frontend jika ada perubahan UI baru.
7. Jalankan smoke test:
   - buka `https://portal.bizone.id`
   - login admin
   - buka wallet
   - buat top up Midtrans
   - cek payment order dan saldo setelah notification sukses.

## Catatan Keamanan

- `.env` sudah di-ignore dan tidak ikut commit.
- Beberapa credential pernah muncul di chat/screenshot, jadi untuk production live sebaiknya rotate credential final.
- `deploy/debian12/app.env.example` sudah dibersihkan agar hanya berisi placeholder.