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.

1. Backend tambahkan route /v1/* paralel dengan path lama (alias). Semua handler sama, hanya pendaftaran route baru.
2. Frontend per modul migrasi pelan-pelan ke path /v1/*.
3. 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:

1. 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.
2. Revenue + sales outreach blocked — Partner bank/non-bank dan PSP integrator butuh subdomain ini live untuk onboarding. Setiap minggu tertunda = sales pipeline tertahan.
3. 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.
4. 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.
5. 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).

• Update psp-integration-contract.md:
  • §1.1 tabel Public API + §1.2 diagram bi-directional flow → path baru.
  • §2.8 audit log path → /api/psp/v1/*.
  • §3 prefix → /api/psp/v1/*.
  • §6 error format prefix → /api/psp/v1/*.
  • §6 (vhost provisioning) → path baru.
  • §7.2 SLA row → /api/psp/v1/payment-events/transaction.
  • §8 active-only filter → /api/psp/v1/*.
  • §10 Production exposure → updated dengan 2026-05-18 re-probe state (nginx config issue, bukan scaffold).
  • §11.5 Handover Info "Public base URLs" → updated 2026-05-18 state.
  • §12.1 version strategy → "Current: /api/psp/v1/* (explicit v1)".
• Update psp-integration-flow-overview.md (English sudah clean; Indonesian i18n status header → 2026-05-18 + base URL table updated).
• Update psp-events.md — heading & body → /api/psp/v1/payment-events/transaction.
• Update psp-tester.md — port 8081 → 8082.
• Update partner-api-current-state.md — semua /partner/v1/* → /api/partner/v1/*.
• Update partner-v1-api-proposal.md — semua /partner/v1/* → /api/partner/v1/*.
• Update OpenAPI partner-api-openapi-draft.yaml paths: → /api/partner/v1/....
• Update runbooks/partner-access-setup.md — semua /partner/v1/* → /api/partner/v1/*.
• Update development/partner-onboarding-legacy-plan.md — banner post-2026-05-07 ditambah di header (historical content kept as-is).
• Update architecture/merchant-enterprise-architecture-plan.md — tier auth table & auth pattern → path baru.
• Update database/schema/views.md — komentar & test step → path baru.
• Update architecture/partner-access-scope-plan.md — endpoint list → /api/partner/v1/*.
• Update architecture/monorepo-restructure-plan.md — nginx vhost path table → path baru.
• Update architecture/service-topology.md — data flow /api/internal/payment-events/transaction → /api/psp/v1/payment-events/transaction. Plus port dashboard-api 8081 → 8082 (sekalian fix Phase 1 task).
• Update database/schema/schema.md — event_log comment → path baru.
• Sales/integrator outreach: kabarin partner pipeline + PSP integrator bahwa subdomain live. Pakai contract dengan path final (/api/psp/v1/*). Eksekusi setelah Phase 2c/2d done.

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):

• summary/* (7 string) — modul kecil, pilot terbaik
• overview, notifications, health, merchants (~5 string)
• auth/* (dashboard_auth_service.dart, 6 string) + image-proxy template
• reference/* (9 string)
• dev/* (5 string)
• planning/*, planner/*, registration/*, profile/* (~7 string)
• reports/* (13 string)
• sales/* (13 string)
• users-access/* (28 string)
• settings/* (19 string)
• purchasing/* (30 string)
• master-data/* (50 string — paling besar, terakhir)

Per batch:

1. Edit string path di Flutter
2. flutter analyze clean
3. Smoke test fitur terkait di local + staging
4. Deploy frontend, monitor 24 jam
5. 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?

Related

• Setup api-merchant subdomain runbook
• Service Topology
• Partner V1 API Proposal
• PSP Integration Contract