Platform Admin API¶

Kontrak API untuk pemisahan tenant plane dan provider control plane pada workflow subscription/add-on Scola.

Last updated: 2026-04-09

1. Scope¶

Dokumen ini mencakup dua surface yang sekarang dipisahkan:

Tenant plane
src/views/SettingsManagement/SubscriptionStatus.vue
src/views/SettingsManagement/ModuleCatalog.vue
src/views/SettingsManagement/AddonRequestReview.vue
Provider control plane
src/views/Platform/PlatformDashboard.vue
src/views/Platform/PlatformSubscriptionControlPlane.vue
route shell src/router/platformRoutes.js

Semua endpoint memakai Odoo session cookie dan dikirim sebagai POST type='json' (JSON-RPC payload) melalui frontend apiClient.

2. Role Boundary¶

2.1 Tenant-side roles¶

principal
head_admin
admin

Hak tenant-side:

melihat status langganan tenant sendiri
melihat katalog add-on
mengirim request add-on
melihat histori request untuk company aktif

2.2 Provider-side role¶

platform_operator
admin tetap bisa mengakses sebagai superuser/platform superadmin

Hak provider-side:

melihat dashboard lintas tenant
membuka queue request add-on lintas company
menjalankan workflow approval dan provisioning

Pemisahan ini sengaja dibuat supaya head_admin tidak lagi bertindak sebagai operator SaaS/provider.

3. Endpoint Summary¶

3.1 Tenant plane¶

Endpoint	Method	Tujuan	Role
`/api/v1/subscription/status`	`POST`	Snapshot entitlement tenant + request workflow aktif	`admin`, `head_admin`, `principal`
`/api/v1/subscription/catalog`	`POST`	Katalog add-on + prerequisite + installed state	`admin`, `head_admin`, `principal`
`/api/v1/subscription/request-addon`	`POST`	Membuat request add-on baru	`admin`, `head_admin`, `principal`
`/api/v1/subscription/my-requests`	`POST`	Histori request untuk company aktif	`admin`, `head_admin`, `principal`

3.2 Provider control plane¶

Endpoint	Method	Tujuan	Role
`/api/v1/platform/subscription/dashboard`	`POST`	Ringkasan dashboard provider lintas tenant	`admin`, `platform_operator`
`/api/v1/platform/subscription/queue`	`POST`	Queue request/provisioning lintas tenant	`admin`, `platform_operator`
`/api/v1/platform/subscription/action-request`	`POST`	Menjalankan aksi workflow provider	`admin`, `platform_operator`

3.3 Backward-compatible aliases¶

Masih tersedia untuk transisi:

/api/v1/subscription/review-queue
/api/v1/subscription/review-addon

Namun FE aktif sekarang harus memakai prefix /api/v1/platform/subscription/* untuk surface provider.

4. Workflow State Machine¶

State request add-on sekarang:

requested
approved
queued_for_provisioning
provisioning
active
rejected
failed

Aturan penting:

approve tidak lagi menulis entitlement tenant.
Tenant entitlement baru ditulis saat provider menjalankan mark_active.
mark_active gagal jika prerequisite SKU belum terpenuhi atau backend module terkait belum terpasang.
status tenant sekarang membedakan:
add-on yang benar-benar aktif di runtime
request yang masih berjalan di control plane provider

5. Action Contract¶

Request body:

{
  "jsonrpc": "2.0",
  "method": "call",
  "params": {
    "request_id": 12,
    "action": "queue_for_provisioning",
    "note": "Masuk maintenance window Jumat malam."
  }
}

Action yang valid:

approve
reject
queue_for_provisioning
start_provisioning
mark_active
mark_failed

Response sukses:

{
  "success": true,
  "message": "Scola Foundation dimasukkan ke antrian provisioning.",
  "request": {
    "id": 12,
    "company_id": 3,
    "company_name": "SMA Demo",
    "sku": "SC-FOUND",
    "label": "Scola Foundation",
    "state": "queued_for_provisioning",
    "state_label": "Masuk antrian provisioning",
    "activation_status": "queued_for_provisioning",
    "activation_label": "Masuk antrian provisioning",
    "workflow_actions": ["start_provisioning", "mark_active", "mark_failed"]
  }
}

6. Tenant Status Semantics¶

/api/v1/subscription/status sekarang mengembalikan:

enabled_addons
hanya add-on yang benar-benar sudah diaktifkan pada tenant
request_statuses
request company aktif yang masih berjalan atau gagal
request_counts
count per state untuk UI tenant

Implikasi FE:

badge Aktif hanya untuk add-on yang sudah efektif
badge Menunggu review provider / Masuk antrian provisioning / Sedang provisioning berasal dari request_statuses, bukan dari enabled_addons

7. Provider Notifications¶

Saat tenant membuat request baru:

sistem mengirim email best-effort ke semua user provider yang punya role/group platform_operator atau base.group_system
sistem mencoba kirim WhatsApp juga jika model scola.notification.config tersedia dan ada konfigurasi WhatsApp aktif

Catatan penting:

email notification sekarang implementatif dan menjadi baseline yang stabil
WhatsApp bersifat opsional/best-effort
kegagalan notifikasi tidak boleh menggagalkan pembuatan request add-on
delivery dijalankan lewat outbox internal + cron retry, bukan synchronous blocking di request path

8. Tenant Notifications¶

Saat provider mengubah state request (approved, rejected, queued_for_provisioning, provisioning, active, failed):

sistem mengirim email best-effort ke requester dan kontak tenant admin yang relevan
sistem mencoba kirim WhatsApp juga memakai konfigurasi aktif milik company tenant bila tersedia
notifikasi bersifat informatif; kegagalan kirim tidak boleh membatalkan transisi workflow
delivery tenant juga diproses asynchronous lewat queue internal yang retry berkala

9. FE Expectations¶

Tenant settings tidak lagi menampilkan tombol approve/reject.
Provider workflow hanya muncul di shell /platform/*.
Menu platform memakai capability platform.*, bukan settings.school.view.
Jika nanti ditambah automation provisioning penuh, update state machine dan file ini bersama-sama.