Sikathree Master PRD

0.1 Pernyataan produk

Sikathree — Sistem Informasi K3 adalah aplikasi web multi-organisasi untuk mendukung tiga domain yang berdiri sendiri tetapi memakai fondasi bersama: HIRADC, Laporan Bahaya, dan Learning Management System (LMS). Sikathree membantu Operator/Petugas mencatat bahaya dan menjalankan tugas, Pengawas K3 melakukan review dan verifikasi sesuai izin, pengelola organisasi mengatur keanggotaan, dan Admin K3 mengelola materi pembelajaran global.

Pengalaman pengguna menggunakan Modern Operational Dashboard (A), Light Mode, responsif sepenuhnya pada desktop, tablet, dan smartphone. Alur lapangan (Laporan Bahaya dan Control Task) didesain mobile-first. Satu akun dapat mempunyai membership di beberapa organisasi; data tenant tidak otomatis terlihat oleh role global.

0.2 Tujuan dokumen

Master PRD ini adalah spesifikasi end-to-end untuk dua tahap implementasi: (1) Interactive Prototype frontend dengan mock data yang saling terhubung dan simulator workflow; (2) MVP Full System dengan frontend, backend, database, file storage, worker, deployment, serta security controls nyata. Dokumen juga memisahkan go-live gates sebelum pemakaian data operasional sungguhan.

0.3 Keputusan paling utama

• Frontend: Next.js App Router, TypeScript, Tailwind CSS, shadcn/ui, React Hook Form + Zod, TanStack Query, dan tRPC BFF.
• Backend: NestJS modular monolith, REST /api/v1, worker terpisah, PostgreSQL + pgvector; transactional outbox untuk email; Garage S3 untuk berkas.
• Tenant isolation: membership dan Dynamic RBAC diperiksa di backend; PostgreSQL Row Level Security (RLS) dengan konteks transaksi; immutable business versions dan append-only audit.
• Infrastruktur: 1 VPS per environment (Production 1 dan Staging 1), masing-masing menggunakan 5 Compose project modular. Hanya Nginx mempublikasikan port 80/443; layanan lain memakai Docker network internal. Tidak menggunakan WireGuard antarservice.
• Capacity assumption: 4.000 akun terdaftar, estimasi 3% aktif bersamaan = 120 peak concurrent users; 8 vCPU/32 GB merupakan kandidat pengujian, bukan kapasitas yang telah dibuktikan.
• Keamanan produksi: pengujian RLS, otorisasi, konsistensi transaksi, object storage, dan backup/recovery harus selesai sebelum mengelola data nyata.

0.4 Status spesifikasi

Dokumen memakai label [FINAL] untuk keputusan percakapan yang sudah dikunci, [DESIGN] untuk rancangan detail yang didelegasikan pengguna dan direkomendasikan sebagai baseline implementasi, [PROVISIONAL] untuk kebutuhan yang masih perlu disahkan sebelum menjadi konfigurasi production, dan [GATE] untuk kriteria wajib sebelum go-live. Penetapan [DESIGN] bukan berarti klaim sudah terimplementasi atau lolos pengujian.

0.5 Prioritas keberhasilan

1. Proses bisnis dan histori yang benar, terutama approval, versi, residual risk, dan aturan attempt LMS.
2. Tidak ada kebocoran data antarorganisasi atau peningkatan hak akses tanpa izin.
3. Pengalaman mobile yang nyaman untuk pekerjaan lapangan tanpa menghilangkan kemampuan desktop.
4. Dapat dioperasikan/diobservasi pada staging, lalu dipromosikan ke production melalui release terotorisasi.
5. Perilaku UI, API, database, audit, dan email saling konsisten; tidak ada hanya-perubahan-badge.

1.1 Penetapan status dan pengendalian perubahan

• [FINAL] Keputusan yang telah disepakati dalam diskusi: stack inti, tiga domain, aturan bisnis spesifik, satu VPS per environment, Dynamic RBAC, session, mobile responsive, dan mode penyimpanan draft manual.
• [DESIGN] Rekomendasi pengisi celah yang pengguna delegasikan: field-level data, validation details, permission/action mapping, state guards, idempotency, edge cases, acceptance test.
• [PROVISIONAL] Nilai atau batas yang memerlukan kebijakan operator: retention angka final, limit file, durasi grant, provider VPS, domain nyata, detail recovery jawaban tes, dan jalur REST publik.
• [GATE] Ketentuan yang harus diverifikasi sebelum data nyata: backup/recovery, storage durability, tests security/RLS, secrets, alerting, release process, load testing.

Setiap perubahan keputusan [FINAL] memerlukan catatan Decision Record yang mencantumkan keputusan lama, usulan baru, alasan, dampak pada entitas/API/UX, dan persetujuan pemilik produk. Developer atau AI Agent tidak boleh mengubah rule hanya agar implementasi lebih mudah.

1.2 Tahap deliverable

1.3 Termasuk MVP

• Multi-org users, invitation-only account, organization selection, role/permission dinamis, guarded support access.
• HIRADC proposal, risk assessment per record dan versi, K×P, review, kontrol, verifikasi, residual risk, audit dan official PDF snapshot.
• Hazard reporting dari mobile, attachment, approval, penugasan satu PIC aktif, tindakan, verifikasi, revisi substansial, histori dan email penting.
• LMS course global terbit, pre-test, learn manual complete, post-test, attempt quota, fingerprint/versioning, results dan tenant progress monitoring.
• Administration tenant/platform/K3, file lifecycle, notification outbox, staging/prod deployment dan basic observability.

1.4 Tidak termasuk MVP

• AI Learning Companion dan pencarian semantik meskipun pgvector tersedia.
• Simulasi 3D, native mobile apps, offline/PWA, JSA/LOTO workflows, e-certificate, cross-module task orchestration.
• Notification Center in-app, video streaming/transcoding platform khusus, advanced BI, microservices/Kubernetes.
• Multi-node Garage/high availability tidak otomatis masuk scope implementasi MVP awal; tetap menjadi risiko durabilitas yang harus diselesaikan sebelum go-live nyata.

1.5 Asumsi lingkungan

• Organisasi merupakan tenant dengan empat area K3 global yang sama.
• Nama domain dan identitas organisasi contoh dalam spesifikasi adalah placeholder, bukan alamat produksi yang telah diputuskan.
• Semua string locale id-ID, tanggal/jam dipresentasikan WIB (Asia/Jakarta) di UI; event disimpan sebagai UTC timestamp di backend [DESIGN].
• Status organizationId di browser hanya pilihan konteks, bukan sumber kebenaran authorization.

2.1 Model identitas dan membership

Satu User merupakan identitas global. Satu user dapat memiliki nol atau lebih Membership organisasi; setiap membership memiliki satu role lokal aktif dan personnel category terpisah. Role Platform Super Admin dan Admin K3 adalah role platform, bukan membership tenant. Organization Admin tidak otomatis memperoleh izin review HIRADC atau laporan. Platform role tidak otomatis membaca tenant data.

2.2 Aktor utama

2.3 Area/lokasi K3 global [FINAL]

Katalog area berlaku pada HIRADC, Laporan Bahaya, filter, laporan, dan course tagging. Field lokasi spesifik berbentuk teks untuk lokasi lebih rinci. User tidak dapat membuat area global baru dari form tenant.

2.4 Use case end-to-end

1. Operator menemukan kondisi bahaya dan membuat laporan; status, severity, evidence, email dan audit mengikuti rule; Pengawas/penanggung jawab menindaklanjuti hingga verifikasi.
2. Operator menyampaikan usulan identifikasi; pihak berizin melakukan assessment satu risiko per record; Pengawas berbeda dari pembuat risiko/versi menyetujui; kontrol dikerjakan dan diverifikasi.
3. Peserta mengerjakan Pre-Test diagnostik bila aktif, membaca lesson dan menandai selesai manual, kemudian lulus Post-Test sesuai threshold/kuota.
4. Admin K3 menerbitkan lesson/assessment versi baru; identitas lesson dan fingerprint mempertahankan atau mereset progress sesuai perubahan nyata.
5. Organization Admin mengundang anggota, mengubah role dalam delegation ceiling, dan menyetujui/menolak permintaan Support Access.
6. Platform Super Admin mengelola metadata tenant, bukan membaca isi data tenant tanpa izin spesifik.

2.5 Sasaran operasional terukur [DESIGN]

• Pengguna dapat menemukan tindakan utama (buat laporan, tugas, belajar) dari Dashboard atau mobile navigation.
• Semua perubahan bisnis signifikan mempunyai actor, timestamp, reason jika diwajibkan, version ID, dan audit event.
• Seluruh route sensitif mempunyai pemeriksaan permission server-side; tidak bergantung pada hidden UI button.
• Cross-tenant isolation dan no-self-approval HIRADC diverifikasi oleh automated tests.

3.1 Navigasi dan application shells

Aplikasi memiliki satu desain terpusat dengan lima variasi shell: Authentication, Organization, Platform, K3 Content Studio, dan Focused Learning/Assessment. Pada desktop Organization Shell memakai sidebar + topbar; di smartphone memakai topbar, bottom navigation izin-terfilter, dan drawer menu lengkap. Tidak ada fitur berizin yang boleh hilang dari mobile.

3.2 Authentication dan akun

3.3 Organization Workspace

3.4 Administrasi organisasi dan platform

3.5 Route behavior

Semua route mendukung direct link, browser refresh, broken URL, loading/empty/error states, session expiration, dan 403/404. Jangan mengandalkan permission check pada layout saja: page data loader dan action tetap memeriksa izin. URL tenant tidak menyertakan organizationId; konteks dipilih dengan key lokal tepat organizationId dan diteruskan per operasi. Deep link dari email harus mendeteksi tenant mismatch dan menawarkan peralihan hanya jika membership sah.

4.1 Identitas visual [FINAL]

• Modern Operational Dashboard, Light Mode Only, warna primary teal #176B63, accent #249B83, muted #E8F5F0, background #F5F7FA, surface putih #FFFFFF, text #1E293B.
• Semantic success #15803D, warning #B45309, critical #B91C1C, info #2563EB; kontras harus memenuhi WCAG 2.2 AA.
• Font Inter direkomendasikan [DESIGN], body 14–16px, form mobile 16px, heading page desktop 24–28px, mobile 20–24px; 4px spacing scale; radius 8–12px.
• Risiko HIRADC: Low hijau, Moderate biru, High amber, Very High merah. Label selalu tertulis; status workflow tidak disamakan dengan tingkat risiko.

4.2 Breakpoints dan layout [DESIGN]

4.3 Component specification

4.4 UX behavioral rules

• Laporan Bahaya dan HIRADC: Simpan Draft manual, tidak autosave. Tindakan Submit terpisah dan konfirmasi final. Saat belum tersimpan, back/navigation/org switch menampilkan dirty form warning.
• Dashboard: KPI hanya yang berizin; Perlu Tindakan merupakan read-only agregasi dari status modul, bukan Notification Center.
• Detail records: tampilkan owner, organization context, status terpisah, versi efektif, kandidat revisi, histori, evidence.
• Permission: menu berdasarkan effective permission; direct URL dan server mutation tetap diperiksa; denied page tidak membocorkan data record.
• Mobile field operations: form laporan tiga langkah (informasi, evidence/penerima, review); kontrol tugas dan approval mempunyai area sentuh memadai, tidak hanya hover.
• Assessment: Focused Learning Shell menghilangkan navigasi operasional yang mengganggu; belum ada timer wajib yang ditetapkan.
• Feedback: setiap mutation menampilkan pending, success, error atau conflict; jangan mengklaim tersimpan ketika jaringan gagal.

4.5 States universal

Loading/skeleton, empty, error/retry, forbidden, not-found, session expired, organization inactive, unsaved changes, version conflict, concurrent modification, upload failed, timeout/unknown submission outcome, offline/network unavailable, assessment changed. Untuk hasil request ambigu, lakukan read-after-write atau status lookup berbasis idempotency key sebelum menampilkan hasil atau mengulangi mutation.

4.6 Accessibility targets

Keyboard navigation, visible focus ring, descriptive field errors, aria labels, semantic headings, screen-reader status feedback, no color-only indicator, text zoom, touch target 44×44 px sebagai target UX; jangan memblokir browser zoom. Uji Chrome Android, Safari iOS, keyboard mobile, landscape/portrait, viewport 320px dan desktop besar.

5.1 Arsitektur logical [FINAL]

Browser (desktop/mobile)
  | HTTPS + host-only session cookie
  v
Nginx Public Edge :80/:443
  |----> Next.js App Router + tRPC BFF ----> NestJS REST /api/v1 (internal)
  |                                               |--- PostgreSQL + pgvector
  |                                               |--- Garage S3 (internal)
  |                                               `--- Transactional Outbox
  |----> Garage S3 via storage hostname (signed upload/download)
  `----> No other ports exposed

NestJS Worker ----> PostgreSQL outbox, Garage cleanup, SMTP provider
Prometheus/Grafana/Alertmanager/Exporters ----> health metrics + external uptime monitor

5.2 Boundary API [PROVISIONAL DESIGN]

Rekomendasi eksekusi: browser memakai tRPC BFF untuk semua business operations; NestJS REST tetap internal di Docker network; Nginx hanya mempublikasikan web app dan storage signed gateway. Ini mengurangi jalur keamanan ganda. Jika integrasi pihak ketiga membutuhkan public REST kelak, buat keputusan arsitektur terpisah dengan autentikasi dan rate limit sendiri. /api-docs/Scalar harus diproteksi, tidak boleh dipublikasikan secara terbuka.

5.3 Frontend [FINAL]

Next.js App Router, React Hook Form + Zod, TanStack Query untuk query cache, Zustand hanya untuk state lintas-komponen yang tidak lebih tepat dikelola React. Folder fitur: auth, organizations, permissions, dashboard, hazard-reports, hiradc, learning, administration, support-access. dto/handler/service/repository pada frontend bila digunakan merupakan adapter REST ke NestJS, bukan SQL repository. tRPC mengirim organizationId terverifikasi dan cookie session ke backend.

5.4 Backend [FINAL]

NestJS modular monolith; REST controllers -> DTO validation -> guards/policies -> domain service -> database repository dalam transaksi. Worker proses asinkron terpisah; bukan microservice HTTP baru. Gunakan standard error envelope, observability trace correlation ID, idempotency and optimistic concurrency.

5.5 API contract synchronization [DESIGN]

NestJS menghasilkan OpenAPI versioned artifact pada CI; frontend REST adapter dibuat/divalidasi dari kontrak tersebut, disertai contract tests. Perubahan breaking mengikuti /api/v1 policy dan backward-compatible deployment window. Jalur tRPC menyesuaikan schema frontend; browser tidak mengenal kredensial NestJS internal.

5.6 Service responsibility map

5.7 Time, error dan replay

Simpan timestamp UTC, presentasi WIB; semua mutation kritis memakai requestId/idempotencyKey yang stabil antar retry. REST/Next tidak boleh mengasumsikan koneksi timeout berarti server gagal: status mutation perlu dicek ulang. Pertahankan HTTP status 400, 401, 403, 404, 409, 422, 429, 5xx sesuai semantik; rahasiakan detail stack trace.

6.1 Aturan field-level global [DESIGN]

Tabel di bawah merupakan rancangan detail yang didelegasikan oleh pemilik produk. Kolom Draft menentukan apakah field harus terisi saat pengguna menekan Simpan Draft; Submit menentukan apakah field wajib pada aksi final. Auto berarti dihitung/diset oleh server dan tidak dapat diedit klien. Kond. berarti wajib apabila kondisi tertentu terpenuhi. Teks panjang dipangkas whitespace, kosong tidak disamakan dengan 0, datetime disimpan UTC, identifier disimpan sebagai UUID/ULID atau key stabil yang tidak mengandung data pribadi. Semua pilihan katalog berasal dari server dan dipastikan valid saat submit.

• Identitas/role/organization context diambil dari session atau membership; jangan beri field createdBy yang bebas ditentukan frontend.
• Semua mutation perubahan dokumen/submission harus membawa expectedLockVersion dan idempotencyKey pada transport, walaupun UI tidak memperlihatkannya sebagai form field.
• Validasi frontend hanya bantuan UX; NestJS mengulangi validasi dan mengecek rule transaksi.
• Bila angka batas di bawah memerlukan penyesuaian operasional (misalnya ukuran file), simpan sebagai konfigurasi kebijakan, bukan asumsi yang tersebar di UI.
• Untuk form Draft HIRADC/Laporan: penyimpanan manual menerima partial fields yang valid; tidak boleh mengeluarkan status Submitted sebelum seluruh persyaratan final terpenuhi. Draft kosong total ditolak sebagai EMPTY_DRAFT [DESIGN].

6.2 Autentikasi dan akun

6.3 Organisasi, membership dan undangan

6.4 HIRADC — Usulan Bahaya

6.5 HIRADC — Assessment Version

6.6 HIRADC — Control Task dan Review

6.7 Laporan Bahaya — Draft dan Submit

6.8 Laporan Bahaya — Penanganan, Verifikasi, Revisi

6.9 LMS — Course, Lesson, Assessment Authoring

6.10 LMS — Participant dan Attempt

6.11 Evidence, Audit, Email dan Support Grant

6.15 Field dependency dan conditional behavior

6.16 Batasan data dan kontrak input

ID pada daftar harus referentially valid; organizationId diperiksa sesudah autentikasi; sensitive strings tidak masuk audit detail/log; HTML dari editor harus disanitasi dan link/file dikendalikan. Tanggal occurredAt dari pengguna memiliki sumber dan timezone eksplisit. Perubahan versi/approval memerlukan expectedLockVersion. Semua field submission yang optional benar-benar diterima sebagai null/absent oleh backend; jangan mengirim string "undefined" atau menyamakan angka nol dengan tidak terisi.

7.1 Aturan inti otorisasi [FINAL]

• Akses ditentukan dari effective permission + tenant context + record scope + business guard, bukan hanya string nama role. Contoh default role pada tabel ditandai * sebagai pemetaan rekomendasi, bukan hak yang tidak dapat diubah oleh admin.
• Satu user dapat mempunyai beberapa organisasi, tetapi satu membership hanya satu role aktif; kategori personel disimpan terpisah. Organization Admin tidak otomatis Pengawas; Admin K3 tidak otomatis tenant reader; Super Admin tidak otomatis tenant reader.
• Semua endpoint read dan mutation wajib menegakkan policy; frontend PermissionGate hanya aspek UX. Support Access tidak menambah role tenant dan selalu read-only.
• Untuk setiap perubahan izin, event audit merekam actor, role sebelum/sesudah, organisasi, reason bila relevan, waktu dan lock version.

7.2 Permission registry dan action matrix [DESIGN]

7.3 Delegation ceiling & non-escalation

Setiap role lokal memiliki permission efektif subset dari role delegation ceiling milik administrator yang menugaskan. Administrator tidak boleh: memberikan hak yang ia tidak boleh delegasikan, mengubah role dirinya untuk memperoleh hak yang melebihi ceiling, menghapus/menonaktifkan Organization Admin aktif terakhir, memberi platform role melalui tenant role editor, atau mengaktifkan grant Support Access tanpa keputusan target Org Admin.

7.4 UI matrix dan navigation

• Menu ditampilkan apabila setidaknya satu screen/action dalam kategori dapat diakses; tindakan dikontrol terpisah oleh izin spesifik. Jangan tampilkan tombol approval hanya karena user dapat membaca record.
• Dashboard KPI menghitung hanya item yang boleh diakses oleh aktor; jangan menyimpulkan permission dari angka agregat. Filter tenant wajib ikut dalam cache key ['org',organizationId,'user',userId,...].
• Personel yang menerima email berdasarkan klasifikasi Operator/Pengawas tidak otomatis memperoleh hak mutation; read permission harus konsisten agar deep link tidak dead end. Saat perlu, buat scoped read permission dengan tujuan dan audit yang benar, bukan bypass.

7.5 Support Access action limitations

Grant memuat tenant, requester, approving admin, enumerasi resource yang disetujui, valid-from/expiry/revocation, dan READ_ONLY. Tidak boleh wildcard secara default, tidak berlaku ke tenant lain, dan tidak boleh mengedit/export luas kecuali download/preview spesifik tercakup eksplisit. Setiap operasi read menilai grant yang masih aktif pada saat request, sekalipun browser masih menyimpan halaman sebelumnya.

8.1 Sumber kebenaran state

State disimpan di backend untuk MVP. UI membaca kode yang stabil, menerjemahkan via status registry code/label/color/description/allowedActions, dan tidak menentukan perubahan state dengan mutasi lokal. Transition = satu transaksi DB untuk record + version pointer/assignment + audit/outbox yang terkait. Mock prototype menirukan transaksi tersebut dalam state update tunggal.

8.2 State transition matrix [DESIGN]

8.3 Irregular transitions

• HARUS TOLAK: double approval pada version yang sudah diputuskan; publish dua draft yang sama; duplikasi PIC aktif; submit attempt dua kali; self-approve HIRADC; submit atas organisasi lain; verified residual jika masih ada kontrol wajib non-VERIFIED.
• RETRY AMAN: timeout setelah server berhasil, memakai idempotency key yang sama; API mengembalikan hasil operasi pertama atau status final saat lookup. Jangan menaikkan version atau mengirim email berulang.
• KONFLIK: expectedLockVersion tidak cocok menghasilkan 409 VERSION_CONFLICT dengan metadata aman (currentVersion, updatedAt, retryHint); halaman harus reload/compare sebelum retry.
• VERSI EFEKTIF: hanya versi APPROVED/ACCEPTED yang dipakai operasional. Candidate draft/pending tidak menggantikan data efektif. Historic notes/attachments pada versi lama tetap dapat dilihat sesuai izin.

8.4 Status presentation registry (contoh desain)

8.5 Event audit minimum

Setiap event final mempunyai eventId, actorId, organizationId?, entityType, entityId, versionId?, action, prevState, nextState, occurredAt, requestId, reason?. Event audit append-only; catatan baru menambah baris, bukan update lama. Simpan diff field non-sensitif bila perlu tanpa menyimpan kredensial, OTP, atau raw answer key.

9.1 API style and routing policy

• NestJS REST base /api/v1; browser memakai Next.js tRPC BFF sebagai pola pilihan [PROVISIONAL DESIGN]. Backend tetap memverifikasi session, X-Organization-Id yang dinormalisasi BFF, membership, permission, record ownership, RLS. Header dari client publik tidak dipercaya.
• OpenAPI versioned artifact menjadi kontrak antarrepository; request/response dan error typed; jangan menyalin DTO manual tanpa contract test.
• Default pagination cursor/limit untuk daftar besar; limit 1..100 [DESIGN], sort key whitelist; semua filter server-side juga scoped pada tenant.

9.2 Endpoint inventory (representatif dan normatif secara fungsi, path exact [DESIGN])

9.3 Standard successful result envelope

{
  "data": { "id": "record-123", "status": "PENDING_REVIEW", "lockVersion": 3 },
  "meta": { "requestId": "req-abc", "serverTime": "2026-11-05T09:00:00Z" }
}

9.4 Standard domain error envelope

{
  "error": {
    "code": "VERSION_CONFLICT",
    "message": "Data telah diperbarui oleh pengguna lain.",
    "details": { "currentLockVersion": 4 },
    "requestId": "req-abc"
  }
}

Jangan masukkan stack trace, email/OTP/raw cookie, maupun existence detail untuk record tenant yang tidak berizin ke error response.

9.5 Payload Laporan Bahaya - submit

{
  "organizationId": "org-a",
  "draftId": "draft-118",
  "expectedLockVersion": 1,
  "idempotencyKey": "03d6cf5e-9d18-4a19-9ed5-fdeec3ad9d6a",
  "report": {
    "reportTypeId": "UNSAFE_CONDITION",
    "severityId": "CRITICAL",
    "areaId": "AREA_DISINFECTION",
    "specificLocation": "Ruang klorinasi",
    "occurredAt": "2026-11-05T09:00:00Z",
    "title": "Kondisi berbahaya pada sistem desinfektan",
    "description": "Deskripsi faktual hasil pengamatan petugas.",
    "immediateAction": "Area dibatasi dan pengawas dihubungi.",
    "evidenceIds": ["ev-001"],
    "extraRecipientMembershipIds": ["mem-009"]
  }
}

Expected: acceptanceStatus=ACCEPTED, handlingStatus=UNASSIGNED, generated report number, new effective revision, audit event, urgent outbox; tidak langsung COMPLETED.

9.6 Payload HIRADC - submit version

{
  "organizationId": "org-a",
  "riskId": "risk-001",
  "assessmentVersionId": "assess-003",
  "expectedLockVersion": 2,
  "idempotencyKey": "d48d7139-0eb6-402e-82db-82e9d111c040",
  "assessment": {
    "areaId": "AREA_PROCESS_CHEMICAL",
    "workActivity": "Penyiapan bahan kimia proses",
    "hazardSource": "Paparan bahan kimia dalam penyiapan",
    "riskEvent": "Paparan tidak disengaja",
    "potentialImpact": "Gangguan keselamatan operator",
    "existingControls": "Instruksi kerja dan APD sesuai prosedur",
    "initialLikelihoodK": 4,
    "initialSeverityP": 4,
    "plannedResidualK": 2,
    "plannedResidualP": 3,
    "assessmentRationale": "Berdasarkan kondisi pekerjaan dan kontrol yang direncanakan",
    "controlIds": ["control-01", "control-02"]
  }
}

Expected: skor awal 16/Very High; planned residual 6/Moderate; verified residual tetap belum ada. Assessment version menjadi pending review; keputusan harus oleh reviewer yang bukan pencipta record/versi.

9.7 Payload approval dan concurrency

{
  "organizationId": "org-a",
  "assessmentVersionId": "assess-003",
  "decision": "APPROVE",
  "reason": null,
  "expectedLockVersion": 3,
  "idempotencyKey": "f4e22221-40c8-4ad2-962d-fb67cdd937a3"
}

Guard: hiradc.assessment.review, reviewer bukan creator risiko/versi, still pending, version lock cocok; update pointer effective + audit dalam satu transaction.

9.8 Payload LMS attempt start & submit

{
  "organizationId": "org-a",
  "courseId": "course-gas-klor",
  "assessmentVersionId": "post-v2",
  "idempotencyKey": "04d6d12e-63b3-48bb-9b0a-e0cd2c4a03f0"
}

{
  "organizationId": "org-a",
  "attemptId": "attempt-003",
  "expectedLockVersion": 5,
  "idempotencyKey": "b42c7212-a183-4370-b57a-8d810b35ed49",
  "answers": [
    { "questionId": "q1", "selectedOptionId": "opt-b" },
    { "questionId": "q2", "selectedOptionId": "opt-c" }
  ]
}

Backend menghitung score dan menyimpan answer snapshot yang berkaitan dengan assessment version. Answer key tidak pernah dimasukkan ke participant-facing payload.

9.9 Upload presign response (illustrative)

{
  "data": {
    "evidenceId": "ev-001",
    "method": "PUT",
    "uploadUrl": "https://storage.example.invalid/signed/object?...",
    "requiredHeaders": { "Content-Type": "image/jpeg" },
    "expiresInSeconds": 300,
    "state": "PENDING"
  }
}

Signed URL memakai host yang sesuai dengan signature dan dilayani Nginx langsung ke Garage; query string, method dan signed headers tidak boleh dimodifikasi client/proxy. example.invalid adalah placeholder, bukan URL produksi.

9.10 BFF session mapping

Next.js membaca host-only HttpOnly session cookie, meneruskan credential ke NestJS dengan mekanisme internal aman, mengambil organizationId eksplisit dari tRPC operation, melakukan input validation, lalu NestJS menegakkan scope. BFF tidak boleh membuat header X-Organization-Id dari state sembarang tanpa validasi business session; NestJS tetap menolak header palsu. All unsafe mutations CSRF protected.

10.1 Design principles

Relational PostgreSQL adalah single source of truth untuk sesi, organisasi, transaksi domain, LMS, outbox dan audit. pgvector tersedia tetapi fitur AI di luar MVP. Gunakan migration versioned, foreign key, NOT NULL dan CHECK/UNIQUE untuk invariants yang dapat ditegakkan DB. Public IDs sebaiknya UUID/ULID; official_no urutan bisnis yang diterbitkan di dalam transaksi dan unik per tenant.

10.2 Logical schema dan tabel utama [DESIGN]

10.3 Tenant keys and RLS

• Pada setiap tabel tenant, gunakan organization_id NOT NULL, indeks (organization_id, status, created_at) atau indeks komposit sesuai pola query, dan composite FK pada semua relasi tenant agar join antar-tenant tidak mungkin secara struktural.
• Application DB role bukan owner tabel dan tidak memiliki BYPASSRLS; migration menggunakan role terpisah. Terapkan ENABLE ROW LEVEL SECURITY dan FORCE ROW LEVEL SECURITY jika owner path masih mungkin, beserta explicit USING/WITH CHECK untuk SELECT/INSERT/UPDATE/DELETE yang perlu.
• Saat request tenant: ambil DB connection dalam transaction; setelah server memvalidasi session & membership, jalankan SELECT set_config('app.organization_id', $1, true) atau SET LOCAL di transaction yang sama, serta context user/grant bila perlu. Query dan commit dijalankan dalam transaction tersebut; pool connection tidak boleh mewarisi context request sebelumnya.
• RLS bukan satu-satunya authorization: NestJS policy memeriksa effective permission + ownership + workflow state dan support grant scopes. Super Admin tidak diberi bypass tenant RLS untuk support access. Jika support read menuntut mekanisme berbeda, rancang narrowly-scoped database function/service with audit and deny-write, lalu uji secara khusus.
• Background worker menggunakan service account dengan kebijakan spesifik dan audit; jangan memakainya untuk melakukan operasi lintas tenant generik tanpa scoping.

10.4 Transaksi dan locking

• submitHazardReport: validasi draft, row lock, nomor resmi unik, accepted if critical, current revision, audit, outbox satu transaksi.
• reviewHIRADC: lock assessment version + risk pointer, enforce reviewer not creator of risk/version, conditional status update, append audit, commit.
• reassignPIC: close existing active assignment + insert new active within transaction; partial unique index rejects races.
• verifyResidual: evaluate all required controls in consistent transaction snapshot, lock relevant version/task, then store verified K/P and audit.
• startAttempt: lock participant+assessment quota row or equivalent serialized key, count in-progress/submitted/abandoned, exclude interrupted-by-update, insert once by idempotency.
• publishCourse: validate draft, lock course, snapshot lessons+assessment fingerprint, atomically switch published version pointer, queue optional event; avoid mass-update all participants synchronously.

10.5 Immutable history

Status workflow changes may update mutable head/pointer rows, but approved assessment versions, accepted report revisions, published lessons/questions, issued PDF manifests, and audit/note/event rows are immutable. Do not soft-delete or hard-delete business history through generic cleanup task. Revocation and expiry append new event or update narrow revocation status without rewriting original approval facts.

10.6 Migration safety

One-shot migration Compose job using separate privileged DB credential; take backup first for production; schema changes expand -> deploy -> contract, keep rollback window. Explicit migration lock and do not allow two concurrent migration jobs. API readiness blocks until schema compatible; never silently run destructive migration at every container startup.

11.1 Session model [FINAL]

• Akun invitation-only; tidak ada registrasi publik.
• Email/password; hash password dengan Argon2id atau alternatif modern yang ditinjau [DESIGN].
• Session opaque token dalam cookie HttpOnly, Secure pada HTTPS, SameSite yang sesuai threat model, host-only cookie (tanpa Domain untuk wildcard tenant), masa idle 60 menit dan absolute 7 hari.
• Sesi disimpan PostgreSQL dengan hash token dan metadata security minimum; idle expiry digeser melalui aturan throttled refresh yang aman; logout/revoke mengakhiri akses di server.
• Reset password memakai OTP 6 digit berlaku 5 menit, hash OTP, batas percobaan, single-use, anti-enumeration dan throttle permintaan. Bukan jawaban rahasia.

11.2 Authentication sequence

Login page -> tRPC BFF -> NestJS /auth/login -> PostgreSQL session
  -> response Set-Cookie host-only; BFF forwards approved cookie flags
  -> workspace resolver -> active membership/global role -> dashboard

Auth middleware menangani routing untuk UX, tetapi server policy dan PostgreSQL RLS tetap sumber enforcement. Session yang sudah kedaluwarsa harus menolak request walaupun UI masih terbuka. Cookie tidak boleh dicatat di request logs.

11.3 CSRF, XSS dan web security

Mutasi cookie-auth wajib menggunakan perlindungan CSRF (token synchronizer/double-submit dengan desain yang sesuai atau strict origin checks + defense in depth) dan validasi Origin/Host, bukan hanya SameSite. Terapkan CSP yang sesuai Next.js dan media editor, sanitasi konten rich text Tiptap, safe HTML rendering, output escaping, dan anti-clickjacking. Rate-limit login, OTP, review, file sign, attempt start, dan operasi sensitif. CORS untuk presigned Garage hanya pada origin Sikathree yang diizinkan dan required methods/headers.

11.4 Authorization model

Evaluasi session -> platform role or tenant membership -> effective permissions -> record scope/ownership -> workflow guard -> RLS. Apabila langkah mana pun gagal, fail closed. Audit setiap grant, review, role change, approval, publish, export dan support-read yang diwajibkan. Semua resource endpoints memakai opaque IDs; invalid cross tenant ID menghasilkan 404/403 yang tidak membocorkan eksistensi resource.

11.5 Security and privacy handling

• Jangan masukkan password, OTP, session, full presigned URL, answer key, PII sensitif, atau raw rich text berbahaya pada log JSON.
• Link evidence harus signed, short TTL, scope-aware, dan diregenerasi setelah grant/konteks berubah. Download endpoint menerapkan authorization saat menerbitkan URL; expired grant tidak boleh menerbitkan URL baru. Catat bahwa URL yang telah diterbitkan mungkin valid hingga TTL selesai; gunakan TTL pendek dan gateway controls untuk risiko revoke instan.
• Global Admin K3 melihat content, bukan nilai peserta; Platform Super Admin melihat metadata, bukan konten tenant. Khusus support access, tenant admin menyetujui resource, waktu, dan tujuan spesifik.
• File types diverifikasi oleh backend setelah upload; antivirus/malware scanning bila risiko dan kebijakan operasional menuntutnya [GATE evaluasi].

11.6 Security testing [GATE]

Uji IDOR lintas organisasi, role escalation, missing RLS context, SQL policy bypass via table owner, forced browsing, CSRF, XSS rich text, session fixation/revocation, invite/OTP replay, duplicate operations, signed URL scope, and support grant expiration. Tidak cukup hanya berasumsi aman karena tombol UI tersembunyi.

12.1 Garage S3 file lifecycle [FINAL]

Browser -> BFF/API: upload initialization (filename, size, MIME, purpose)
API -> DB: FileObject PENDING + scoped object key + short TTL presign
API -> Browser: signed PUT URL + required headers
Browser -> Nginx storage hostname -> Garage (no NestJS binary proxy)
Browser -> API: finalize evidence with id + integrity metadata
API -> Garage: head/check; DB FileObject UPLOADED
API domain mutation -> DB transaction: FileAttachment ATTACHED to record/version
Worker cleanup: old PENDING or UPLOADED orphan, never valid ATTACHED history

Pada awal prototype, file hanya metadata/local preview; real storage harus mengikuti presigned URL S3, DNS yang valid, CORS dan signed host preservation. storage.sikathree.web.id pernah dipakai sebagai contoh hostname; nama final perlu konfirmasi DNS/ownership [PROVISIONAL]. Nginx mesti meneruskan method, signed Host/headers dan query tanpa transformasi yang membatalkan signature.

12.2 Storage policy [DESIGN]

• MIME allowlist awal: JPEG, PNG, WebP, PDF; format lainnya hanya setelah kebutuhan diverifikasi. Batas contoh JPEG/PNG/WebP <=10MB/file dan PDF <=20MB/file; angka dapat dikonfigurasi serta memerlukan uji provider/kapasitas.
• Object keys opaque dan tidak memasukkan email, nama atau secret. Metadata DB menyimpan tenant/purpose/version/scope.
• Unduh/view melalui short-lived signed GET yang hanya diberikan setelah record access check; file global authoring punya scope tersendiri.
• Worker masuk Docker network storage karena harus dapat membersihkan object orphan; gunakan credential worker yang dibatasi untuk prefix sementara.
• PENDING/UPLOADED/ATTACHED dibedakan jelas pada UI. Kegagalan upload/finalize/attach tidak boleh menampilkan file sebagai evidence final.

12.3 Single-node durability risk [GATE]

Garage single-node dengan replication factor 1 tidak menyediakan redundansi antar-node. Boleh untuk staging dan demo, tetapi tidak boleh dianggap cukup tahan kegagalan untuk evidence nyata tanpa strategi pemulihan dan keputusan risiko yang disahkan. Backup & Disaster Recovery detail sengaja tetap backlog sesuai diskusi, namun keberadaannya tidak menghapus status wajib sebelum go-live real data.

12.4 Transactional outbox [FINAL]

• Setiap tindakan penting (submit laporan, laporan kritis, review/assignment/completion/reopen, dan event penting lain yang disepakati) membuat outbox record dalam transaksi DB yang sama.
• Worker polling FOR UPDATE SKIP LOCKED, claim job terbatas, retry dengan exponential backoff + jitter, dedup event/recipient, delivery attempt logging, dead-letter/final failure handling. Delivery semantics at-least-once attempt, bukan exactly-once guarantee.
• Penerima laporan baru: seluruh anggota aktif kategori Operator/Pengawas organisasi, pelapor, penerima tambahan yang dipilih; dedup berdasarkan identitas/email. Reviewer/admin lain mendapat email sesuai event policy, bukan broadcast semua event LMS rutin.
• Laporan CRITICAL: ACCEPTED otomatis, priority email urgent, tidak otomatis COMPLETED. Jika email gagal, status laporan tetap valid dan worker retry; masalah email terlihat di monitoring.
• Staging menggunakan sink email test (misalnya Mailpit), tidak mengirim email ke pengguna production.

12.5 File/audit cleanup

Cleanup registry menggunakan whitelist eksplisit dan retention TTL bernomor dari konfigurasi; hanya temporary file, expired token, expired session atau cache tepercaya yang boleh dibersihkan. Tabel business history, revisions, audit log dan attachment valid tidak boleh masuk daftar generic cleanup. Jalankan dry-run dan uji foreign key dependencies sebelum mengaktifkan scheduled job.

13.1 Topology [FINAL]

Terdapat dua VPS total: 1 Production VPS dan 1 Staging VPS, bukan dua VPS per environment. Seluruh service tiap VPS berjalan lewat lima project Docker Compose terpisah dan external Docker networks internal. Tidak membutuhkan WireGuard atau inter-VPS private IP untuk komunikasi service pada satu environment.

13.2 Five Compose projects

13.3 Docker networks dan trust boundaries

• sikathree_edge: reverse proxy Nginx, Next.js, NestJS API. Internal API tidak publish host port.
• sikathree_backend: API, worker, Postgres. internal: true sesuai kemampuan Compose dan kebutuhan worker; tidak buka DB ke internet.
• sikathree_storage: Nginx storage gateway, NestJS API, worker cleanup, Garage. Internal service port, bukan host-published.
• sikathree_metrics: monitoring dan exporter; akses Grafana dibatasi via admin/private auth, tidak diekspos tanpa proteksi.
• sikathree_outbound: worker membutuhkan outbound SMTP/API sesuai konfigurasi (network egress policy dan internal network split harus diuji agar DNS berfungsi). Hanya Nginx mempublikasikan host ports 80/443. Gunakan Docker name stability dan external networks untuk menghubungkan Compose projects; health checks dan startup dependency tidak diasumsikan lintas project.

13.4 Kandidat kapasitas [DESIGN, memerlukan load test]

13.5 Data growth and capacity model

4.000 akun bukan ukuran disk utama; volume file berasal dari laporan, foto evidence, materi LMS, retensi, dan audit. Sebelum go-live, lakukan survei jumlah laporan/berkas, proyeksi pertumbuhan minimal 12 bulan, IOPS, throughput HTTP, kapasitas email worker, dan disk headroom. Hindari menempatkan service monitoring pada disk penuh tanpa retensi.

13.6 Environment separation

Production dan Staging memiliki environment secret, PostgreSQL, Garage, session namespace, Mailpit/test SMTP, DNS/HTTPS, metrics dan data berbeda. Tidak ada copy data production ke staging tanpa sanitasi dan approval. Persisted Docker volumes tidak dibagikan antar-environment.

13.7 Secrets and runtime config

Credential database, session, S3, SMTP dan container registry runtime disimpan di VPS masing-masing, diinjeksikan via Compose secrets atau mekanisme secret file yang aman (/run/secrets), bukan variabel NEXT_PUBLIC atau GitHub Actions secret untuk runtime app. GitHub Actions hanya memegang credential deploy yang minimal dan audit-approved. Images dipromosikan berdasarkan immutable digest, staging -> production.

13.8 Availability and disaster recovery [GATE]

Single VPS adalah single point of failure; single-node Garage tidak redundan. Pemulihan data PostgreSQL, objek Garage, config, deployment artifacts, serta tes restore belum dibahas tuntas dan tetap ditempatkan pada backlog wajib. Production real-data launch diblok sampai RPO/RTO, backup off-host/restore rehearsal, key escrow, dan ownership disepakati serta diverifikasi.

14.1 Source control architecture

Dua repository produk: sikathree-web (Next.js frontend + tRPC BFF) dan sikathree-api (NestJS API/worker/migrations). Penempatan sumber konfigurasi infra, Nginx, Garage dan monitoring perlu ditetapkan sebagai ownership eksplisit; jangan diam-diam menciptakan repository ketiga jika belum disetujui.

14.2 CI pipeline setiap repo [DESIGN]

1. Pull request: lint, typecheck, formatting, unit tests, security scanning, dependency audit, OpenAPI contract comparison, build and smoke test.
2. Build multi-stage Docker image yang berjalan non-root, menghasilkan SBOM/attestation jika tool tersedia, tag commit SHA dan immutable digest.
3. Push image ke GitHub Container Registry (GHCR) hanya setelah CI lulus.
4. Deploy staging otomatis setelah syarat branch/CI yang ditetapkan; tetap dengan environment terisolasi.
5. Jalankan one-off migration bila kompatibel, health check, E2E smoke, responsive smoke di staging.
6. Production release hanya setelah approval/manual authorized release; promote digest yang sama dari staging, bukan rebuild source yang berbeda.
7. Post-release health, rollback to previous digest jika schema backward-compatible; jangan rollback sembarangan setelah destructive migration.

14.3 Deployment security

GitHub workflow memakai scoped credentials dan pinned actions bila mungkin; development runtime secrets tidak masuk repository, build logs atau image layers. Audit siapa menyetujui/release. Manual workflow_dispatch saja tidak selalu sama dengan two-person approval; pilih mekanisme policy yang benar-benar ditegakkan dan sesuai GitHub plan/repo visibility.

14.4 Next.js build-time config

NEXT_PUBLIC_* dapat di-inline pada build. Gunakan konfigurasi yang tidak berubah antar-staging/production pada artifact promosi atau pola runtime config yang diuji; jangan menyematkan URL/kredensial staging ke image yang dipromosikan production.

14.5 Release readiness checklist

• [ ] Staging build SHA/digest exact cocok dengan target production.
• [ ] OpenAPI contract kompatibel.
• [ ] Schema migration rehearsal dan backup valid.
• [ ] RLS/authorization tests lulus.
• [ ] E2E critical paths mobile & desktop lulus.
• [ ] Alerting, metrics, logging dan external uptime aktif.
• [ ] Secrets, DNS, TLS, Nginx CORS/signed URL diverifikasi.
• [ ] Load testing kapasitas target terdokumentasi.
• [ ] Backup/restore dan storage durability go-live gate terpenuhi.
• [ ] Approval production tercatat dan incident owner siap.

15.1 Practical Observability [FINAL]

Pada setiap VPS: Prometheus, Grafana, Alertmanager, Node Exporter, Postgres exporter, Garage metrics, NestJS API metrics dan worker/outbox metrics, Nginx access/error counts; external uptime check dari luar VPS. Aplikasi menulis structured JSON logs dengan Docker local logging driver + rotation. Loki dan Tempo belum termasuk MVP awal.

15.2 Golden signals [DESIGN]

15.3 Labels, logs and privacy

Gunakan label metrik rendah cardinality seperti route template/status class/operation, jangan menambahkan raw userId, reportId, email, answerId, file keys, atau signed URL ke Prometheus labels. Structured logs memakai requestId/traceId; audit bisnis berada PostgreSQL append-only terpisah dari log runtime yang dirotasi. Redact secrets dan konten pribadi dari logs.

15.4 Alert examples [DESIGN]

• API 5xx error rate meningkat selama 5–10 menit; p95 above agreed SLO (alert thresholds perlu tuning dari load test).
• Postgres connections at high watermark, deadlock spike, disk usage >80%, outbox oldest pending > defined operational limit.
• Garage failed requests or object read checksum errors.
• External uptime detects HTTPS unavailable independent of local VPS monitoring.
• Critical alerts have owner, severity, runbook link dan non-email single point of notification risk evaluated.

15.5 Operational docs

Dokumentasikan dashboard utama, query untuk domain errors, alert severity, siapa on-call, deploy/rollback, rotate credentials dan runbook incident. Test alerts in staging before go-live. Monitoring stack sendiri perlu memory/disk budget dan protected access.

16.1 Normal / abnormal / adverse path policy

Edge case diuji pada tiga lapis: domain service (unit/integration), API/database authorization dan transaksi (integration/security), lalu UI E2E desktop/mobile. Implementasi dianggap benar hanya bila result, audit/history dan state setelah refresh konsisten; toast sukses saja tidak cukup.

16.2 Edge case & acceptance matrix [DESIGN]

16.3 Response time dan reliability target [PROVISIONAL baseline]

• Operasi API umum p95 <1 detik; mutasi kritis p95 <2 detik di luar upload/video transfer, pada workload staging target; threshold final ditetapkan setelah benchmark.
• HTTP 5xx <1% pada uji peak dan 0 data integrity violations pada transaksi kritis; no extra accepted reports, duplicate attempt results, double approval, maupun cross-tenant leak.
• Uji beban bertahap 30, 60, 120 concurrent virtual users, lalu stress 180 dan 240. Virtual users mengikuti skenario think-time dan mix aktivitas; 120 VUs bukan 120 request/detik.
• Mobile UX target 320–430px dan tablet/desktop; WCAG 2.2 AA target audit; test on Chrome Android and Safari iOS using actual devices or representative emulation.

16.4 Definition of acceptance

Setiap use case diterima jika (1) prasyarat & izin tepat, (2) UI form/feedback benar, (3) backend mengubah state yang benar, (4) tenant row security lolos, (5) event/versi tercatat, (6) email/file side effect konsisten, (7) refresh dan navigasi mobile menampilkan hasil benar, (8) negative and concurrency case ditolak secara aman.

17.1 Test pyramid

TypeScript unit tests untuk pure rules, NestJS integration tests dengan PostgreSQL RLS nyata, contract tests OpenAPI dan frontend adapters, Playwright E2E desktop/mobile, security/adversarial tests, dan k6 capacity tests. Mock prototype berguna untuk UX tetapi tidak menggantikan integration test pada backend real.

17.2 Test plan matrix

17.3 Twelve end-to-end business journeys

T-01: login/membership/org switch; T-02: hazard draft/save/submit; T-03: critical hazard auto acceptance; T-04: reviewer->PIC->action->verification; T-05: accepted report revision; T-06: HIRADC proposal; T-07: risk assessment review with no self approval; T-08: required controls->verified residual; T-09: LMS pre-test->learn->post-test; T-10: content publication/versioning; T-11: member role updates/ceiling; T-12: support grant request->tenant review->read->expiry. Jalankan happy path dan negative path untuk setiap journey.

17.4 E2E browser matrix

Viewport 320, 375, 390, 430, 768, 1024, 1280, dan 1440px; Chrome Android dan Safari iOS representatif, plus desktop Chromium/Firefox/WebKit bila tersedia. Fokus keyboard open, image picker permissions, sticky button safe-area, popup, role-switched navigation, no hover-only actions, web reader typography, and form error announcements.

17.5 Load-test k6 workload [DESIGN]

Mix simulasi awal: 65% browsing/list/detail, 20% HIRADC/Laporan mutations, 10% LMS test, 5% upload/download; proporsi ini hipotesis test, bukan data perilaku nyata. Jalankan warm-up 30 VUs, 60, peak 120, stress 180 dan 240; include think time and realistic requests. Catat 5xx, p95/p99 per route, DB pool wait, PostgreSQL locks, Garage throughput/disk IO, worker lag, CPU/mem and data consistency. Ulangi load test setelah perubahan indeks/schema/infra besar.

17.6 Test evidence

Setiap release menyertakan test report dengan commit/image digest, environment, fixtures, test ID, hasil pass/fail, screenshot responsive, traces, load result, ditemukan bug dan pemilik remediation. Tidak boleh mengklaim 'tested' jika hanya menyiapkan checklist.

18.1 Phase-based delivery

18.2 Implementation order and dependencies

• Mulai dari global identity, membership, permission registry, RLS, auditable transaction primitives; baru domain services.
• Mock adapter dan real adapter mematuhi interface serupa. Prototype fixtures mencakup 2 tenant, ~10 akun, ~20 risk records, ~20 hazard reports, 4 global courses, attempt variants, support grants.
• File upload & outbox perlu service interfaces sejak awal agar domain submit tidak di-hardcode untuk memanggil SMTP langsung.
• Status registry dan field-level Zod schemas harus berkorespondensi dengan NestJS DTO; generated OpenAPI contract mengurangi drift.
• Mobile QA untuk Laporan Bahaya dan control task dilakukan sejak implementasi awal, bukan tahap akhir.

18.3 Ownership and governance

Product owner mengesahkan perubahan business rule, K3 reviewer mengesahkan istilah/prosedur keselamatan, Tech Lead menyetujui API/DB migration, security reviewer menilai RLS/support/signed URLs, frontend lead memvalidasi desktop/mobile. AI Coding Agent adalah pelaksana yang wajib melaporkan changed files, tests, assumption, dan unresolved risk; tidak menjadi pemegang keputusan produk.

18.4 Prototype vs MVP vs Go-live

Prototipe berhasil apabila 12 business journeys berjalan dengan fake data dan responsive UI; MVP berhasil jika backend nyata transaction+tenant isolation benar di staging; production go-live berhasil hanya setelah risk critical seperti backup/recovery, Garage storage durability, credential/monitoring, release approval, dan peak load tervalidasi. Jangan menyamakan ketiga hasil tersebut.

19.1 Prinsip pemilihan

Bagian ini sengaja memuat skill wajib saja. Tidak memasukkan Find Skills, Skill Installer, Image Gen, OpenAI Docs, Reverse Engineer Anything, accessibility additional skill, maupun GitHub Actions Efficiency sebagai skill opsional. Ketujuh skill dari screenshot yang sebelumnya dinilai wajib tetap tercakup; beberapa skill eksternal wajib melengkapi backend, database, security, Docker dan testing. Skill yang fungsinya tumpang tindih diaktifkan sesuai jenis pekerjaan, bukan semuanya setiap request.

Tingkat ketersediaan: Skill berlabel Built-in dinilai tersedia berdasarkan screenshot pengguna; path dan versi lokal belum diverifikasi melalui repository agent. Skill eksternal memiliki sumber publik untuk diverifikasi ulang sebelum instalasi. Semua skill bersifat panduan kualitas, tidak lebih tinggi dari PRD/peraturan keamanan.

19.2 Mandatory external / built-in skills registry

19.3 Tiga mandatory custom Sikathree skills [DESIGN]

Ketiga custom skill disertakan sebagai file agent-skills/custom/*/SKILL.md asli, bukan hanya referensi nama. Skill Creator dipakai ketika memperbarui skill tersebut. Skill custom wajib menyebut PRD chapter/decision source dan tidak boleh menyalin kredensial.

19.4 Mandatory agent execution rules

1. Baca AGENTS.md, index PRD dan custom skill yang relevan sebelum menulis code domain; baca external skill yang sesuai task.
2. Hierarki keputusan: hukum dan kebijakan keamanan > keputusan produk [FINAL] dalam PRD > [DESIGN] terdelegasi > skill guidance > kebiasaan agent. Jika konflik, laporkan, jangan mengubah silently.
3. Untuk setiap task, catat: feature scope, route, input/output DTO, permission key, state guard, tenant scope, files changed, tests added/run, hasil/resiko.
4. Skill Next.js dari Aurora berorientasi App Router dan dapat menyarankan Server Actions, tetapi tidak boleh menggantikan kontrak Next.js tRPC BFF -> NestJS REST tanpa approval.
5. Skill Supabase dipakai untuk PostgreSQL umum, bukan menginstal Supabase Auth/Storage. Skill Docker hanya untuk Docker Compose 1 VPS/environment yang sudah dipilih.
6. Jangan menjalankan command dari third-party SKILL.md tanpa meninjau script, permission, network access, filesystem writes dan version pinning. Sumber eksternal dicatat dengan commit SHA/tag setelah dipilih; jangan mengklaim pinned bila belum.
7. Review Agent, Web Design Guidelines dan Playwright dipakai sebagai quality gates sesuai fase: code review, UI audit, actual browser tests.
8. Skill Creator wajib untuk pemeliharaan skill internal, tidak perlu dimuat untuk semua pekerjaan coding harian.

19.5 Skill-to-workstream mapping

19.6 Instalasi dan verifikasi

Perintah yang telah disediakan hanya contoh, belum dijalankan. Jangan mengunduh seluruh eksternal skills otomatis pada mesin production. Gunakan lockfile/commit pin di tahap implementasi; README paket mencantumkan lokasi dan perintah. Simpan external skill sebagai dependency links, tidak mendistribusikan kembali konten pihak ketiga di ZIP.

20.1 Decision ledger

Agar developer tidak mengarang aturan bisnis, daftar berikut harus dikonversi menjadi Architecture Decision Record saat menghasilkan keputusan baru. Open decisions tidak boleh diinterpretasikan sebagai fitur yang sudah disahkan production.

20.2 Risiko utama

20.3 Go-live blocker checklist

• [ ] Tenant isolation and RLS prove fail-closed under active membership, revoked membership, and connection pooling.
• [ ] Security audits cover session/CSRF/OTP, cross-tenant IDOR, role escalation and Support Access read-only expiry.
• [ ] Garage durability and backup/DR policy are approved and recovery verified on test data.
• [ ] Production secrets and TLS configured; no staging/prod cross-connect.
• [ ] 120 concurrent mixed-load target tested on staging-comparable infra with integrity checks.
• [ ] Authorized production release approval, digest promotion, migration rehearsal, rollback conditions and monitoring are documented.
• [ ] Mobile E2E critical journeys and accessibility review pass.
• [ ] Business workflows signed off by K3/product stakeholders including field catalogue K/P descriptions, hazard severity and workflow rules.

21.1 Terms and glossary

21.2 Source of decisions

Dokumen ini disusun berdasarkan kesepakatan langsung dalam diskusi proyek Sikathree sampai 5 November 2026: tiga modul, empat area K3, Dynamic RBAC, sesssion, multi-tenancy/RLS, frontend Next.js tRPC, NestJS REST+worker, PostgreSQL/pgvector, Garage, satu VPS per environment, Docker Compose modular, practical observability, UI/UX direction A dan 120 concurrent estimate. Field/action/state/edge-cases tambahan diberi label [DESIGN] dan belum diklaim sebagai hasil survei lapangan.

21.3 External technical references (informational, subject to version review)

• Next.js App Router: https://nextjs.org/docs/app
• NestJS: https://docs.nestjs.com/
• PostgreSQL RLS: https://www.postgresql.org/docs/current/ddl-rowsecurity.html
• Docker Compose networks: https://docs.docker.com/compose/how-tos/networking/
• Garage S3: https://garagehq.deuxfleurs.fr/documentation/
• Playwright: https://playwright.dev/
• Grafana k6: https://grafana.com/docs/k6/latest/
• Agent skill registry dan custom skills dijabarkan pada Bab 19 serta berkas agent-skills/ dalam ZIP.

21.4 Traceability guidance

Gunakan ID requirement sederhana REQ-{DOMAIN}-{NNN}, referensi route, permissionKey, state transition, affected tables, API operation, dan test ID pada tiket developer. Tidak ada requirement considered Done tanpa evidence implementation, test, screenshot/trace bagi mobile workflow, serta review permission dan tenant-scoping.

21.5 Document maintenance

Untuk revisi PRD, tingkatkan versi dokumen, catat perubahan keputusan [FINAL]/[DESIGN]/[PROVISIONAL], regenerasikan Markdown + PDF + HTML + prd.json dari satu source konten agar hasil saling konsisten. Jika menyetujui keputusan provisional, pindahkan ke [FINAL] via change log dan tambahkan test.