Skip to main content

Submission V2 Structure Rules (Prompt-Ready)

1. Prinsip Utama​

  1. submission-v2 adalah context orkestrasi transisi workflow berbasis action.
  2. Orkestrator harus tetap tipis: koordinasi flow di submission-v2.service.ts, detail domain/persistence dipisah ke service khusus.
  3. Behavior perubahan status harus tetap traceable ke log wxl_submission_log.
  4. Semua perubahan harus behavior-preserving kecuali ada kebutuhan bisnis baru yang eksplisit.

2. Struktur Folder Standar​

submission-v2/
  docs/
    STRUCTURE-RULES.md
    submission-v2-system-behavior.md
  submission-v2.service.ts
  submission-v2-snapshot.service.ts
  submission-v2-persistence.service.ts
  submission-v2-log.service.ts
  submission-v2.types.ts
  submission-v2.service.spec.ts

3. Tanggung Jawab Tiap File​

3.1 submission-v2.service.ts​

  1. Entry point setSubmission(...).
  2. Menentukan urutan orkestrasi flow end-to-end.
  3. Validasi guard orchestration (override source, reason, status transition).
  4. Tidak menyimpan query SQL langsung selain operasi insert/update final yang memang bagian orkestrasi.

3.2 submission-v2-snapshot.service.ts​

  1. Resolve snapshot workflow dari submission existing atau load fresh dari tabel master.
  2. Validasi keberadaan workflow/action di snapshot.
  3. Tidak menangani update submission/entity.

3.3 submission-v2-persistence.service.ts​

  1. Operasi persistence submission/entity dan sinkronisasi tabel native.
  2. Validasi keamanan identifier tabel (isSafeIdentifier) dan validasi payload kolom.
  3. Menjadi satu-satunya tempat query information_schema.columns untuk context ini.

3.4 submission-v2-log.service.ts​

  1. Hitung snapshot approval dari config action.
  2. Build payload log wxl_submission_log.
  3. Tidak melakukan insert DB langsung.

3.5 submission-v2.types.ts​

  1. Kontrak payload/return/service internal (SetSubmissionPayload, SetSubmissionResult, ApprovalSnapshot, dsb).
  2. Menjadi referensi typing lintas service dalam context.

3.6 submission-v2.service.spec.ts​

  1. Unit test utama untuk behavior SubmissionServiceV2, SubmissionV2LogService, dan SubmissionV2SnapshotService.
  2. Menjaga regression untuk flow create/update submission, approval, native payload, dan snapshot.

3.7 docs/*​

  1. submission-v2-system-behavior.md menjelaskan behavior runtime implementasi saat ini.
  2. STRUCTURE-RULES.md menjadi aturan refactor dan penempatan logic context.

4. Aturan Boundary (Hitam Putih)​

  1. Logic approval snapshot hanya di submission-v2-log.service.ts.
  2. Logic load snapshot workflow hanya di submission-v2-snapshot.service.ts.
  3. Logic sinkronisasi entity native (status_id, submission_id, native payload) hanya di submission-v2-persistence.service.ts.
  4. submission-v2.service.ts tidak boleh menambahkan knowledge schema tabel entity native.
  5. Integrasi transport (HTTP controller/worker consumer) tetap berada di context pemanggil, bukan di folder submission-v2.

5. Aturan Refactor​

  1. Ubah struktur/naming dulu, hindari ubah behavior dalam satu langkah besar.
  2. Jika menambah service baru, tentukan boundary sejak awal: snapshot, log, persistence, atau orchestration.
  3. Bila menambah field payload/return, update sekaligus:
  • submission-v2.types.ts
  • caller API/worker yang relevan
  • test unit/integration terkait
  • dokumentasi submission-v2-system-behavior.md
  1. Jangan menghapus validasi guard (override, reason, status transition) tanpa keputusan bisnis tertulis.

6. Aturan Testing Minimum​

  1. Jalankan unit test context:
  • packages/lib/src/service/workflow-action/submission-v2/submission-v2.service.spec.ts
  1. Jalankan integration test endpoint v2:
  • apps/api/src/api/core/workflow/workflow.submission-v2.integration.spec.ts
  1. Verifikasi minimal skenario ini tetap lolos:
  • create submission baru
  • update submission existing
  • guard error (Submission not found, invalid override source, missing reason)
  • native payload filtering/validasi
  • approval snapshot dan quorum behavior

7. Prompt Refactor (Siap Pakai)​

Refactor `packages/lib/src/service/workflow-action/submission-v2` dengan aturan:
- pertahankan boundary orchestration/snapshot/persistence/log
- jangan ubah behavior runtime `setSubmission(...)` kecuali diminta
- jaga error contract yang sudah dipakai caller
- update docs `submission-v2-system-behavior.md` jika ada perubahan behavior

Setelah refactor:
1. jalankan unit test submission-v2
2. jalankan integration test endpoint `/api/workflow/submission/v2`
3. laporkan file yang dipindah/diubah dan risiko behavior