API Versioning v1 — Migration Plan

Plan to introduce a consistent /v1/... path style across the Kesles Merchant API surface. Created 2026-05-07. Code-side rename PSP & Partner sudah dieksekusi (Phase 2a + 2b done). Nginx vhost api-merchant.kesles.com LIVE secara DNS/TLS/process per 2026-05-18 tapi config proxy masih strip prefix → 3/8 probe Phase 2d gagal (lihat Phase 2c/2d). Yang belum tuntas: nginx config fix, dokumentasi sisa (Phase 2e), dan seluruh Phase 1, 3-6.

Status (2026-06-24): Phase 2 shipped. api-merchant.kesles.com live dengan path versioned: /api/psp/v1/ → :8082 (dashboard_api lookup), /api/partner/v1/ → :8086 (partner_service, sudah diekstrak dari merchant_core_api), /api/integration/v1/ → :8092 (integration_api). Narasi "PARTIAL / strip prefix / 3/8 probe gagal" di bawah adalah snapshot historis saat planning; config nginx sekarang sudah benar.

Decision log:

2026-05-07 — PSP path shape: /api/psp/v1/* (with /api/ prefix). Payment-events nested under PSP namespace.
2026-05-07 — Partner path: rename /partner/v1/* → /api/partner/v1/* untuk konsisten dengan PSP. Aman dilakukan sekarang karena api-merchant.kesles.com belum live = no integrator existing.
2026-05-07..2026-05-17 — Phase 2a (PSP rename) + Phase 2b (Partner rename) selesai di Go code. Verifikasi: 0 string /api/psp/ (tanpa /v1), /api/internal/payment-events, atau /partner/v1 (tanpa /api/) tersisa di services/dashboard_api/ dan merchant_core_api/.
2026-05-17 — Hard rename strategy dipilih (bukan dual-route paralel). Tidak ada masa transisi karena belum ada integrator publik yang pakai path lama.

Goal

Public path on every external/internal HTTPS surface becomes:

<host><nginx-mount-prefix>/v1/<module>/<resource>

Example after migration:

Caller	Final URL
Dashboard SPA → summary	`https://kesles.com/merchant/dashboard-api/v1/summary/recent-transactions`
Dashboard SPA → auth	`https://kesles.com/merchant/dashboard-api/v1/auth/login`
Mobile app → merchant	`https://kesles.com/merchant/api/v1/merchant/transactions`
PSP integrator	`https://api-merchant.kesles.com/api/psp/v1/merchants`
PSP callback	`https://api-merchant.kesles.com/api/psp/v1/payment-events/transaction`
Partner integrator	`https://api-merchant.kesles.com/api/partner/v1/auth/token`

Non-goals

Re-architect ke API gateway baru. Tetap pakai pola nginx → service yang ada.
Pindahkan service. dashboard_api (:8082) dan merchant_core_api (:8080) tetap.
Versi /v2. Saat ini cukup /v1 (semua route current = v1).

Current state (probed 2026-05-07, re-probed 2026-05-17, latest 2026-05-18)

Hostnames

Host	Path mount	Forward	Backend	Live?
`kesles.com`	`/merchant/api/*` (strip prefix)	`:8080`	`merchant_core_api`	✅
`kesles.com`	`/merchant/dashboard-api/*` (strip prefix)	`:8082`	`dashboard_api`	✅ (build URL salah, sedang patut diperbaiki — lihat §1)
`api-merchant.kesles.com`	`/api/psp/v1/*` (preserve)	`:8082`	`dashboard_api`	⚠️ PARTIAL per 2026-05-18: cert SAN ✅ (`CN=api-merchant.kesles.com`, Let's Encrypt E7), vhost ✅, HTTP→HTTPS 301 ✅, backend handler ✅ live di port 8082. Tapi nginx `proxy_pass` strip prefix → backend terima `/merchants` (bukan full path) → `404 route not registered`. Fix config (proxy_pass tanpa trailing slash) di Phase 2c.
`api-merchant.kesles.com`	`/api/psp/v1/payment-events/*` (preserve)	`:8082`	`dashboard_api`	⚠️ PARTIAL (depend Phase 2c fix yang sama)
`api-merchant.kesles.com`	`/api/partner/v1/*` (preserve)	`:8080`	`merchant_core_api`	⚠️ PARTIAL (depend Phase 2c fix yang sama)

Reference: runbooks/setup-api-merchant-subdomain.md — vhost LIVE per 2026-05-18, tapi proxy config masih strip prefix; 3/8 probe Phase 2d masih gagal.

Route surface

dashboard_api (129 total HandleFunc):

Prefix	Count	Module breakdown
`/api/dashboard/*`	108	master-data 18, users-access 17, settings 11, reference 9, purchasing 8, summary 7, sales 7, reports 7, auth 6, dev 5, lainnya
`/internal/dashboard/*`	8	legacy, server-to-server
`/dashboard/auth/*`	6	alias lama auth (paralel dengan `/api/dashboard/auth/*`)
`/api/psp/v1/` + `/api/psp/v1/payment-events/`	(handled in mux)	PSP integrator (post-rename 2026-05-07)

merchant_core_api (~57 total):

Prefix	Count	Catatan
`/auth/*`	8	mobile auth
`/merchant/*`	8	mobile merchant
`/references/*`	7	mobile + dashboard pakai
`/public/*`	5	landing, legal, academy
`/internal/*`	~16	server-to-server (dipanggil `dashboard_api` & whatsapp_service)
`/api/partner/v1/*`	3	rename dari `/partner/v1/*` (Phase 2b done 2026-05-07..2026-05-17) untuk konsisten dengan PSP
`/dashboard/auth/*`	6	duplikasi di kedua service (untuk login dashboard via merchant_core_api juga)

Flutter dashboard side path strings

apps/merchant_dashboard/lib/:

~200+ string literal '/api/dashboard/*' di dashboard_home_api.dart (dominan: master-data 50, purchasing 30, users-access 28, settings 19, sales 13, reports 13, merchants 10)
7 string '/dashboard/auth/*' di dashboard_auth_service.dart
1 string '$dashboardApiBaseUrl/api/dashboard/internal/image-proxy' di dashboard_image_proxy.dart (template)

Mobile app side path strings (`apps/mobile_user/lib/`)

Path style sudah datar (/auth/*, /merchant/*, /references/*, /profile/avatar, /public/umkm-academy). Untuk migrasi tinggal sisip /v1/ di depan tiap path.

Existing API docs (perlu update)

psp/reference/core-api.md — base URL list, semua path mobile
services/dashboard/admin.md + admin-openapi-draft.yaml
apps/mobile_user/api.md + openapi-draft.yaml
api-internal/partner-api-current-state.md — ✅ sudah update ke /api/partner/v1 (Phase 2e done 2026-05-19)
psp/integration/contract.md — ✅ sudah konsisten dengan /api/psp/v1/*
psp/reference/internal-transaction-status.md
architecture/service-topology.md — ✅ port dashboard_api 8081 → 8082 (fix 2026-05-19)

Migration strategy: paralel-alias bertahap

Pakai add-then-remove, bukan hard cut.

Backend tambahkan route /v1/* paralel dengan path lama (alias). Semua handler sama, hanya pendaftaran route baru.
Frontend per modul migrasi pelan-pelan ke path /v1/*.
Setelah semua modul migrate + production stabil ≥ 2 minggu, hapus path lama.

Pertimbangan kenapa paralel:

Deploy frontend dan backend tidak harus serentak — tidak ada window service-down.
Per-modul rollback gampang (frontend revert ke path lama yang masih hidup).
Test integration (psp-tester, partner-tester, mobile dev tester) bisa dipindah satu-satu.

Priority order — kenapa PSP & Partner duluan

PSP + Partner (api-merchant.kesles.com) wajib di-prioritaskan sebelum dashboard SPA & mobile. Alasan:

Belum ada integrator existing — probe 2026-05-07 konfirmasi vhost belum live (per 2026-05-18 vhost sudah dibuat tapi config strip prefix, masih belum bisa dipakai integrator). Tidak ada PSP/Partner yang sudah pakai /api/psp/* atau /api/internal/payment-events/*. Artinya:
- Rename ke /api/psp/v1/* SEKARANG = zero breaking change, tidak perlu grace period, tidak perlu dual-route jangka panjang.
- Kalau ditunda — sekali integrator masuk pakai path lama, rename jadi mahal: koordinasi 90-hari + dual-route maintenance + risiko mereka miss memo.
Revenue + sales outreach blocked — Partner bank/non-bank dan PSP integrator butuh subdomain ini live untuk onboarding. Setiap minggu tertunda = sales pipeline tertahan.
Independen dari pekerjaan dashboard — Phase 1 (fix base URL dashboard) dan Phase 2 (PSP/Partner go-live) bisa jalan paralel: beda host, beda team konsumen, beda artifact deploy.
Partner sudah /v1 — historis di kode hidup sebagai /partner/v1/*, lalu di-rename ke /api/partner/v1/* 2026-05-07 (Phase 2b done). Konsisten dengan PSP. Biaya rendah karena belum ada integrator publik.
Dashboard & mobile punya buffer — keduanya saat ini hidup (atau bisa dibikin hidup via Phase 1). Refactor /v1 di sana risk-nya bisa di-spread ke beberapa minggu tanpa blok bisnis.

Konsekuensi: dashboard SPA + mobile pindah ke phase berikutnya, tapi user-facing tetap stabil karena alias paralel.

Phase 1 — Fix dasar agar production hidup (PRIORITAS HARI INI)

Tidak terkait /v1, tapi blocking untuk deploy berikutnya. Sebelum migrasi /v1 mulai, baseline production harus benar.

Verify build base URL: cek artifact production dashboard saat ini menggunakan DASHBOARD_API_BASE_URL=https://kesles.com/merchant/dashboard-api (sesuai apps/merchant_dashboard/config/flavors/production.json:3). Bug 404 saat ini (/merchant/api/api/dashboard/...) menunjukkan deploy aktual pakai https://kesles.com/merchant/api. Identifikasi siapa override-nya.
Build ulang dengan base URL benar (./scripts/build_dashboard.sh production tanpa DASHBOARD_API_BASE_URL_OVERRIDE).
Smoke test endpoint summary setelah deploy: recent-transactions, txn-trend, kpi, pending-merchants harus 200.
Update service-topology.md: port dashboard_api 8081 → 8082 (sweep 2026-05-19 — done di EN + ID i18n; juga di-fix di psp-tester.md, services/dashboard/admin.md, services/dashboard/deploy.md).

Phase 2 — PSP & Partner go-live dengan `/v1` dari hari pertama 🔴 PRIORITAS

Goal: api-merchant.kesles.com live, dengan path sudah versioned sejak go-live. Tidak ada path lama yang perlu dibuang nanti karena tidak akan pernah dipakai integrator.

Kerjakan paralel dengan Phase 1 (beda team, beda artifact).

2a. Backend rename PSP path di `dashboard_api` ✅ DONE 2026-05-07

File: services/dashboard_api/internal/app/server.go (mux registrations) + handler files terkait.

Lama (sebelum rename)	Baru (live di kode 2026-05-17)
`/api/psp/*`	`/api/psp/v1/*`
`/api/internal/payment-events/*`	`/api/psp/v1/payment-events/*`

Rename HandleFunc registration ke /api/psp/v1/* + /api/psp/v1/payment-events/*. Hard rename tanpa alias (zero integrator existing). Bukti: server.go:312-316.
Update internal dashboard_dev_psp_tester.go allowlist → "/api/psp/v1/merchants", "/api/psp/v1/payment-events/". Bukti: dashboard_dev_psp_tester.go:72-74.
Update psp-sign-post/main.go example path → /api/psp/v1/*. Bukti: psp-sign-post/main.go:2,14.
Handler internal payment-events tetap hidup, path mount baru /api/psp/v1/payment-events/* di psp_event_receiver.go:46-52.
go test ./... clean (assumsi sudah diverifikasi saat merge; verifikasi ulang di sprint berikut).

Verifikasi 2026-05-17: 0 string "/api/psp/" (tanpa v1) dan 0 string "/api/internal/payment-events" tersisa di services/dashboard_api/.

2b. Backend rename Partner path di `merchant_core_api` ✅ DONE 2026-05-07..2026-05-17

Sama strategi seperti PSP: hard rename, tidak alias paralel, karena api-merchant.kesles.com belum live.

Lama (sebelum rename)	Baru (live di kode 2026-05-17)
`/partner/v1/auth/token`	`/api/partner/v1/auth/token`
`/partner/v1/partners/`	`/api/partner/v1/partners/`
`/partner/v1/merchants/`	`/api/partner/v1/merchants/`

Touch list:

merchant_core_api/internal/httpapi/routes_partner.go — 3 HandleFunc registration sudah pakai /api/partner/v1/*. Bukti: routes_partner.go:4-6.
merchant_core_api/internal/httpapi/partner_handlers.go — strings.TrimPrefix sudah pakai /api/partner/v1/. Bukti: partner_handlers.go:108,188.
services/dashboard_api/internal/app/dashboard_dev_partner_tester.go — string literal sudah migrasi (verifikasi via grep: 0 occurrence /partner/v1 tanpa /api/ prefix di file ini).
Comment di services/dashboard_api/internal/app/dashboard_partner_credentials.go:277 sudah pakai /api/partner/v1/auth/token. Comment di server.go di range line 311 area sudah pakai /api/psp/v1/*.
go test ./... clean (assumsi sudah diverifikasi saat merge; verifikasi ulang di sprint berikut).
Smoke test loopback: curl -i -X POST -H 'Content-Type: application/json' -d '{}' http://127.0.0.1:8080/api/partner/v1/auth/token → expect 400/401 JSON. (Re-run sebelum Phase 2c untuk konfirmasi tidak ada regresi.)

Verifikasi 2026-05-17: 0 string /partner/v1 (tanpa /api/ prefix) tersisa di merchant_core_api/ dan services/dashboard_api/.

2c. Provision Nginx vhost `api-merchant.kesles.com` ⚠️ PARTIAL (re-probed 2026-05-18)

Eksekusi runbooks/setup-api-merchant-subdomain.md, tapi dengan path baru (path table di runbook perlu di-update dulu sebelum eksekusi).

Update runbook setup-api-merchant-subdomain.md — path target sudah pakai /v1/* (done 2026-05-07, lihat banner di runbook).
DNS api-merchant.kesles.com resolve ke 103.219.73.98 (Cloudflare). Verifikasi 2026-05-18: dig OK.
Cert Let's Encrypt SAN expand. Verifikasi 2026-05-18: CN=api-merchant.kesles.com, issuer Let's Encrypt E7.
File /etc/nginx/sites-available/api-merchant.kesles.com.conf dibuat & ter-symlink — vhost menjawab dengan header Server: nginx/1.18.0 (Ubuntu) di domain ini.
nginx -t + reload sudah jalan (vhost live).
🔴 Config nginx belum benar — re-probe 2026-05-18 menemukan:
- proxy_pass location /api/psp/v1/ STRIP prefix sebelum forward (backend terima /merchants bukan /api/psp/v1/merchants). Fix: hapus trailing slash di proxy_pass http://localhost:8082;.
- Sama issue di /api/partner/v1/ → port 8080.
- location / masih serve static HTML 200 (last-modified 2026-05-13, 1945 bytes). Plan: return 404 JSON.
- Detail diagnosa & action items di runbook §Deployment status.

2d. Re-probe + tag LIVE ⚠️ PARTIAL (re-probed 2026-05-18)

Probe path baru dari luar VM. Ekspektasi response:

TLS cert SAN include api-merchant.kesles.com. ✅ 2026-05-18.
curl -i https://api-merchant.kesles.com/api/psp/v1/merchants → 401 JSON {"error":"missing_auth_headers", ...} (bukan 404 Express). ❌ 2026-05-18 actual: 404 {"error":"not_found","message":"route not registered: /merchants"} — nginx strip prefix.
curl -i -X POST https://api-merchant.kesles.com/api/psp/v1/payment-events/transaction → 401 JSON. ❌ 2026-05-18 actual: 404 JSON route not registered: /payment-events/transaction — sama issue.
curl -i -X POST -H 'Content-Type: application/json' -d '{}' https://api-merchant.kesles.com/api/partner/v1/auth/token → 400/401 JSON dari merchant_core_api. ❌ 2026-05-18 actual: 404 page not found plain text (Go default NotFound) — sama issue.
curl -i https://api-merchant.kesles.com/partner/v1/auth/token → 404 (path lama tidak ada — konfirmasi rename Partner berhasil). ✅ 2026-05-18: 404 nginx (bukan dari vhost lain).
curl -i https://api-merchant.kesles.com/ → 404 JSON {"error":"not_found"} (bukan landing HTML). ❌ 2026-05-18 actual: 200 HTML 1945 bytes — root masih serve static.
curl -i http://api-merchant.kesles.com/ → 301 redirect ke HTTPS. ✅ 2026-05-18.
curl -i https://api-merchant.kesles.com/api/psp/merchants → 404 (path lama tidak ada — konfirmasi rename). ✅ 2026-05-18: 404 nginx.

Done state Phase 2d: semua 8 probe ✅. Sekarang 5/8 ✅, 3/8 ❌. Belum bisa di-tag LIVE — depend fix nginx config di Phase 2c.

2e. Komunikasi & dokumentasi PSP/Partner ✅ DONE 2026-05-19

Status 2026-05-19: semua source markdown PSP/Partner sudah pakai /api/psp/v1/* & /api/partner/v1/*. Verifikasi via grep: 0 string /api/psp/* (tanpa v1), /api/internal/payment-events, atau /partner/v1 (tanpa /api/) tersisa di file target (kecuali setup-api-merchant-subdomain.md yang sengaja keep legacy probe + partner-onboarding-legacy-plan.md sebagai historical placeholder dengan banner update).

Done state Phase 2: api-merchant.kesles.com berjalan, dokumentasi konsisten dengan path baru, integrator pertama bisa onboard pakai contract final.

Phase 3 — Backend: tambah alias `/v1/*` untuk dashboard SPA & mobile

Pekerjaan ini tidak blok bisnis (dashboard saat ini hidup, mobile saat ini hidup). Boleh dikerjakan setelah Phase 2 selesai atau paralel kalau resource cukup.

3a. `dashboard_api` (`services/dashboard_api/internal/app/server.go`) — dashboard SPA modules

Tambahkan kompanion route per modul. Skema mapping:

Lama	Baru (alias paralel)
`/api/dashboard/auth/*`	`/v1/auth/*`
`/api/dashboard/summary/*`	`/v1/summary/*`
`/api/dashboard/overview`	`/v1/overview`
`/api/dashboard/notifications`	`/v1/notifications`
`/api/dashboard/master-data/*`	`/v1/master-data/*`
`/api/dashboard/users-access/*`	`/v1/users-access/*`
`/api/dashboard/settings/*`	`/v1/settings/*`
`/api/dashboard/reference/*`	`/v1/reference/*`
`/api/dashboard/purchasing/*`	`/v1/purchasing/*`
`/api/dashboard/sales/*`	`/v1/sales/*`
`/api/dashboard/reports/*`	`/v1/reports/*`
`/api/dashboard/dev/*`	`/v1/dev/*`
`/api/dashboard/registration/*`	`/v1/registration/*`
`/api/dashboard/planning/*`	`/v1/planning/*`
`/api/dashboard/planner/*`	`/v1/planner/*`
`/api/dashboard/profile/*`	`/v1/profile/*`
`/api/dashboard/transactions`	`/v1/transactions`
`/api/dashboard/users`	`/v1/users`
`/api/dashboard/merchants`	`/v1/merchants`
`/api/dashboard/internal/image-proxy`	`/v1/internal/image-proxy`
`/api/dashboard/health`	`/v1/health`
`/internal/dashboard/*`	(tetap — server-to-server, tidak public-facing)

PSP path tidak masuk tabel ini karena sudah ditangani Phase 2 (rename, bukan alias).

Tambah handler registration paralel (1 commit per modul, biar revert kecil).
Test lokal: panggil path lama dan baru → response identik.
Update handleRoutes() table supaya /routes endpoint nge-list keduanya selama transition.

3b. `merchant_core_api` (`internal/httpapi/routes_*.go`) — mobile modules

Lama	Baru
`/auth/*`	`/v1/auth/*`
`/merchant/*`	`/v1/merchant/*`
`/references/*`	`/v1/references/*`
`/profile/avatar`	`/v1/profile/avatar`
`/public/*`	`/v1/public/*`
`/dashboard/auth/*`	(deprecated di service ini — dashboard via dashboard_api saja)
`/internal/*`	(tetap — server-to-server)
`/api/partner/v1/*`	(di-handle Phase 2 — bukan dashboard SPA / mobile concern)
`/webhook/whatsapp`	`/v1/webhook/whatsapp` (opsional — webhook biasanya tidak di-version)
`/health`, `/health/otp-runtime`, `/metrics`	(tetap — operational, tidak di-version)

Tambah handler paralel di routes_auth.go, routes_merchant.go, routes_reference.go, routes_public.go.
Test integration suite existing (yang hit path lama) tetap hijau.

Phase 4 — Frontend migration per modul

4a. Dashboard (`apps/merchant_dashboard/`)

Per modul, ganti string path. Urutan disarankan dari yang paling kecil → besar (biar mudah validasi):

Per batch:

Edit string path di Flutter
flutter analyze clean
Smoke test fitur terkait di local + staging
Deploy frontend, monitor 24 jam
Lanjut batch berikutnya

4b. Mobile (`apps/mobile_user/`)

Single batch (path-nya datar, jumlah sedikit):

Konstanta base path dari '' jadi '/v1' (atau prefix di constructor HTTP client).
Test flow login → register → transaction → home dashboard.
Deploy via store update (bertahap karena rollout mobile lebih lambat).
Catatan: backward-compat alias di backend wajib hidup MINIMAL 6 bulan setelah mobile rollout, karena user lama tidak auto-update.

Phase 5 — Update dokumentasi (untuk dashboard SPA & mobile, melanjutkan Phase 2e)

Phase 2e sudah cover dokumentasi PSP & Partner. Phase ini cover sisanya:

core-api-reference.md — ubah base URL contoh dari https://kesles.com/merchant/api → https://kesles.com/merchant/api/v1. Semua heading endpoint dapat /v1 prefix.
dashboard-admin.md + admin-openapi-draft.yaml — server URL + paths.
merchant-mobile-api.md + openapi-draft.yaml.
internal-transaction-status.md.
service-topology.md — Data Flow /api/internal/payment-events/* → /api/psp/v1/payment-events/* (done 2026-05-19) + port dashboard_api 8081 → 8082 (done 2026-05-19 di Phase 1).
Tambah CHANGELOG di doc utama dengan tanggal cut-over per phase.

Phase 6 — Hapus alias lama dashboard SPA & mobile (≥ 2 minggu setelah Phase 4-5 stabil)

Khusus alias paralel yang dibuat di Phase 3. PSP path tidak punya alias (Phase 2 rename langsung), jadi tidak ada cleanup PSP di sini.

Pre-condition: telemetry dari dashboard_api dan merchant_core_api confirm 0 hit ke path lama dari traffic yang bukan mobile-old-version.

Tambah logging hit-counter per route lama (1 minggu observe).
Stop registration /api/dashboard/* di dashboard_api.
Stop registration /auth/*, /merchant/*, /references/*, /public/*, /profile/avatar di merchant_core_api.
Mobile alias TETAP HIDUP sampai store rollout coverage ≥ 95% (target: 6-12 bulan).
Update /routes table di dashboard_api — list /v1/* saja.

Risk register

Risk	Mitigation
Frontend migrate tapi backend belum deploy → 404	Backend deploy DULU per modul, frontend mengikuti. Smoke test path baru sebelum frontend deploy.
Mobile app lama hit path lama setelah dihapus	Alias mobile path tahan ≥ 6 bulan + telemetry hit-counter.
Webhook eksternal (PSP, Partner) hit path lama	Tidak applicable saat ini — `api-merchant.kesles.com` belum live, tidak ada integrator yang pakai path lama. Rename PSP `/api/psp/` → `/api/psp/v1/` aman tanpa grace period. Setelah Phase 2 live, mitigation untuk masa depan: simpan changelog versioning + 30-hari notice kalau ada `/v2/*` di kemudian hari.
Cert + Nginx vhost di Phase 2 lupa SAN expand	Wajib `nginx -t` + re-probe 6 cek runbook sebelum sebut LIVE.
Doc tidak sinkron dengan kode	OpenAPI spec di-generate dari handler code (auto), bukan ditulis manual. Kalau belum ada generator: review checklist dokumentasi sebelum tag release.

Validation criteria (Done = bisa di-tag `v1.0.0`)

Phase 1 selesai: production dashboard SPA hidup (404 /api/api/dashboard/... saat ini hilang).
Phase 2 selesai: 8 probe api-merchant.kesles.com dengan path baru lulus, integrator pertama berhasil onboard pakai /api/psp/v1/* atau /api/partner/v1/*.
Phase 3 selesai: /v1/* route count match /api/dashboard/* route count untuk dashboard_api; analog untuk merchant_core_api.
Phase 4 selesai: 0 string '/api/dashboard/' di apps/merchant_dashboard/lib/. Mobile baseline pakai /v1/.
Phase 5 selesai: semua doc API sudah pakai /v1. service-topology.md akurat.
Phase 6 selesai: telemetry konfirmasi 0 web traffic ke path lama dashboard/mobile selama 1 minggu sebelum delete.

Estimasi effort (rough)

Phase	Effort	Blok bisnis?
1 (fix base URL dashboard)	0.5 hari	✅ user dashboard production rusak
2 (PSP & Partner go-live)	2 hari (rename PSP + rename Partner + Nginx vhost + docs PSP/Partner)	✅ integrator onboarding blocked
3a (dashboard_api alias dashboard SPA)	1 hari	❌
3b (merchant_core_api alias mobile)	0.5 hari	❌
4a (frontend dashboard 13 modul, batch)	3-4 hari (inkremental, ~1 modul per deploy cycle)	❌
4b (frontend mobile)	0.5 hari + window store rollout	❌
5 (docs sisanya)	0.5 hari	❌
6 (cleanup, after observation period)	0.5 hari	❌
Total	9-9.5 hari engineering + window observasi 2-4 minggu + window store rollout 6-12 bulan

Phase 1 + 2 = ~2 hari → bisa selesai dalam 1 sprint week, melepas semua blocker bisnis. Sisanya (Phase 3-6) kerjaan sequencing yang bisa di-spread tanpa urgensi.

Open questions

Wajib diputus sebelum Phase 2 mulai

PSP path shape: /api/psp/v1/* ✓ (diputus 2026-05-07). Konsekuensi: ada inkonsistensi dengan Partner di poin berikutnya.
PSP payment-events path: /api/psp/v1/payment-events/* ✓ (anak dari namespace PSP, mengikuti keputusan pertama). Payment-events memang traffic dari PSP gateway (payment.kesles.com), masih dalam namespace PSP integration.
Partner path consistency: opsi B ✓ (diputus 2026-05-07). Partner di-rename /partner/v1/* → /api/partner/v1/* agar konsisten dengan PSP. Touch list di Phase 2b.
PSP rename strategy: hard rename ✓ (diputus & dieksekusi 2026-05-07). Dev-tester di dashboard SPA sudah di-update bareng, tidak ada konsumen eksternal, jadi alias paralel tidak diperlukan.

Wajib diputus sebelum Phase 3 mulai

Dashboard auth path: /dashboard/auth/login (tanpa /v1) saat ini hidup di dua service. Setelah migrasi: cukup di dashboard_api saja /v1/auth/login? Atau biarkan duplikasi?
Webhook path: /v1/webhook/whatsapp atau biarkan /webhook/whatsapp (tanpa version, ikut konvensi banyak provider)? — Default rekomendasi: tanpa version, karena webhook biasanya identifier per provider.
Health/metrics: di-version atau tidak? Default rekomendasi: TIDAK (operational endpoint, tidak ikut API contract).
Internal server-to-server /internal/*: di-version atau tidak? Default rekomendasi: TIDAK (bukan public surface, dideploy bareng caller).

Wajib diputus sebelum Phase 6 mulai

Grace period mobile: berapa lama alias backend dipertahankan setelah app store rollout? 6 bulan atau 12 bulan?

Goal​

Non-goals​

Current state (probed 2026-05-07, re-probed 2026-05-17, latest 2026-05-18)​

Hostnames​

Route surface​

Flutter dashboard side path strings​

Mobile app side path strings (apps/mobile_user/lib/)​

Existing API docs (perlu update)​

Migration strategy: paralel-alias bertahap​

Priority order — kenapa PSP & Partner duluan​

Phase 1 — Fix dasar agar production hidup (PRIORITAS HARI INI)​

Phase 2 — PSP & Partner go-live dengan /v1 dari hari pertama 🔴 PRIORITAS​

2a. Backend rename PSP path di dashboard_api ✅ DONE 2026-05-07​

2b. Backend rename Partner path di merchant_core_api ✅ DONE 2026-05-07..2026-05-17​

2c. Provision Nginx vhost api-merchant.kesles.com ⚠️ PARTIAL (re-probed 2026-05-18)​

2d. Re-probe + tag LIVE ⚠️ PARTIAL (re-probed 2026-05-18)​

2e. Komunikasi & dokumentasi PSP/Partner ✅ DONE 2026-05-19​

Phase 3 — Backend: tambah alias /v1/* untuk dashboard SPA & mobile​

3a. dashboard_api (services/dashboard_api/internal/app/server.go) — dashboard SPA modules​

3b. merchant_core_api (internal/httpapi/routes_*.go) — mobile modules​

Phase 4 — Frontend migration per modul​

4a. Dashboard (apps/merchant_dashboard/)​

4b. Mobile (apps/mobile_user/)​

Phase 5 — Update dokumentasi (untuk dashboard SPA & mobile, melanjutkan Phase 2e)​

Phase 6 — Hapus alias lama dashboard SPA & mobile (≥ 2 minggu setelah Phase 4-5 stabil)​

Risk register​

Validation criteria (Done = bisa di-tag v1.0.0)​

Estimasi effort (rough)​

Open questions​

Wajib diputus sebelum Phase 2 mulai​

Wajib diputus sebelum Phase 3 mulai​

Wajib diputus sebelum Phase 6 mulai​

Related​