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 tipis: flow di submission-v2.service.ts, query dipindah ke repository.
  3. Pisahkan read-query dan write-command untuk menjaga readability dan testability.
  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.repository.ts
  submission-v2-command.repository.ts
  submission-v2-log.service.ts
  submission-v2.types.ts
  submission-v2.service.spec.ts
  submission-v2.repository.spec.ts

3. Tanggung Jawab Tiap File​

3.1 submission-v2.service.ts​

  1. Entry point setSubmission(...).
  2. Menentukan urutan flow end-to-end.
  3. Validasi guard orchestration (override, reason, workflow/action ownership, status transition).
  4. Tidak boleh berisi query DB langsung.

3.2 submission-v2.repository.ts​

  1. Read-query data live (wxl_submission, wml_workflow, wml_action).
  2. Lock submission row (pessimistic_write) untuk flow update.
  3. Tidak mengandung write/update command.

3.3 submission-v2-command.repository.ts​

  1. Operasi write/command submission/entity (insert, update, sync).
  2. Validasi keamanan identifier tabel (isSafeIdentifier) dan validasi payload kolom.
  3. Menjadi tempat query information_schema.columns untuk context ini.

3.4 submission-v2-log.service.ts​

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

3.5 submission-v2.types.ts​

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

3.6 submission-v2.service.spec.ts​

  1. Unit test utama orkestrasi SubmissionServiceV2.
  2. Menjaga regression flow create/update submission dan guard validation.

3.7 submission-v2.repository.spec.ts​

  1. Unit test read repository.
  2. Menjaga behavior lock/read dan validasi input read path.

4. Aturan Boundary (Hitam Putih)​

  1. Logic approval snapshot hanya di submission-v2-log.service.ts.
  2. Read-query workflow/action/submission hanya di submission-v2.repository.ts.
  3. Write-command submission/entity/log hanya di submission-v2-command.repository.ts.
  4. submission-v2.service.ts tidak boleh menambahkan knowledge schema tabel entity native.
  5. Integrasi transport (HTTP/worker) tetap di context pemanggil.

5. Aturan Refactor​

  1. Ubah struktur/naming dulu, hindari ubah behavior dalam satu langkah besar.
  2. Jika menambah field payload/return, update sekaligus:
  • submission-v2.types.ts
  • caller API/worker terkait
  • unit/integration test terkait
  • submission-v2-system-behavior.md
  1. Jangan menghapus guard (override, reason, status transition) tanpa keputusan bisnis tertulis.
  2. Hindari menambah query DB langsung ke submission-v2.service.ts.

6. Aturan Testing Minimum​

  1. Jalankan unit test context:
  • packages/lib/src/service/workflow-action/submission-v2/submission-v2.service.spec.ts
  • packages/lib/src/service/workflow-action/submission-v2/submission-v2.repository.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/workflow/action invalid)
  • native payload filtering/validasi
  • approval quorum behavior

7. Prompt Refactor (Siap Pakai)​

Refactor `packages/lib/src/service/workflow-action/submission-v2` dengan aturan:
- pertahankan boundary orchestration/read-repository/command-repository/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