Skip to main content

Cross-Workflow Structure Rules (Prompt-Ready)

Dokumen ini adalah standar struktur folder dan tanggung jawab file untuk apps/worker-workflow/src/cross-workflow.

1. Prinsip Utama​

  1. Gunakan pola consumer -> service -> repository.
  2. Pisahkan behavior relation ONE_TO_MANY dan MANY_TO_ONE ke service berbeda.
  3. Hindari shared service besar yang berisi banyak if relation.
  4. Semua query DB berada di repository.
  5. Utility harus pure function tanpa DI.

2. Struktur Folder Standar​

apps/worker-workflow/src/cross-workflow/
├── cross-workflow.module.ts
├── constants/
├── types/
├── docs/
├── repositories/
├── services/
└── utils/

Struktur file runtime minimum:

services/
  cross-workflow.consumer.ts
  cross-workflow.service.ts
  cross-workflow-one-to-many.service.ts
  cross-workflow-many-to-one.service.ts
repositories/
  cross-workflow.repository.ts
types/
  cross-workflow.interface.ts
utils/
  cross-workflow-log.util.ts
  relation-type.util.ts
  identifier.util.ts

3. Tanggung Jawab Tiap Layer​

3.1 consumer​

Boleh:

  • decode/filter CDC payload
  • mapping CDC -> CrossWorkflowTriggerPayload
  • manual ack/nak
  • panggil CrossWorkflowService.execute(...)

Tidak boleh:

  • query DB kompleks
  • transaction boundary bisnis
  • relation readiness logic

3.2 cross-workflow.service.ts (orchestrator)​

Boleh:

  • buka/commit/rollback transaction
  • resolve SubmissionServiceV2 via request context
  • load source submission + cross-workflow connections via repository
  • routing relation type ke service relation

Tidak boleh:

  • query mapping/detail SQL relation
  • logic field mapping detail

3.3 cross-workflow-one-to-many.service.ts​

Boleh:

  • seluruh behavior relation ONE_TO_MANY
  • mapping source->target entity
  • create missing target submission
  • execute target submission existing

3.4 cross-workflow-many-to-one.service.ts​

Boleh:

  • seluruh behavior relation MANY_TO_ONE
  • mapping source->target entity (target field dipatok id)
  • readiness gate sibling milestone
  • create missing target submission dengan barrier config action target:
    • baca wml_action.is_cr_trgt_empty_conn
    • jika false, skip auto-create saat koneksi kosong dan tulis reason log
  • execute target submission existing setelah ready

3.5 cross-workflow.repository.ts​

Boleh:

  • semua read/write query yang dibutuhkan cross-workflow
  • lock read/write query untuk submission
  • lookup information_schema.columns
  • caching check kolom fisik

Tidak boleh:

  • keputusan orchestration relation

3.6 types/​

  • boundary payload/type lintas file
  • tidak boleh ada query/DI

3.7 utils/​

  • pure helper (normalizeRelationType, formatter log, validasi identifier)
  • tidak boleh akses DB

4. Aturan Naming​

  • *.consumer.ts untuk adapter transport.
  • *.service.ts untuk orchestration/use-case.
  • *-one-to-many.service.ts khusus relation ONE_TO_MANY.
  • *-many-to-one.service.ts khusus relation MANY_TO_ONE.
  • *.repository.ts untuk query DB.
  • *.interface.ts atau *.types.ts untuk boundary payload/type.
  • *.util.ts untuk pure helper.

5. Aturan Boundary (Hitam Putih)​

  1. Query DB hanya di cross-workflow.repository.ts.
  2. cross-workflow.service.ts hanya routing/orchestration, tidak boleh query mapping detail.
  3. Behavior ONE_TO_MANY dan MANY_TO_ONE tidak boleh digabung ke satu relation service.
  4. Shared helper boleh di utils/, bukan shared business service.
  5. Consumer tidak boleh tahu detail relation/mapping.
  6. Auto-create target saat koneksi kosong wajib hormati wml_action.is_cr_trgt_empty_conn dan wajib tulis reason saat skip.

6. Aturan Refactor​

  1. Pertahankan behavior runtime kecuali ada requirement eksplisit.
  2. Jika ubah kontrak payload, update bersamaan:
  • types/cross-workflow.interface.ts
  • consumer/service yang memakai kontrak
  • test terkait
  • dokumentasi behavior
  1. Jika menambah query, letakkan di repository.
  2. Jika menambah branch relation baru, buat service relation khusus.

7. Aturan Testing Minimum​

  1. Unit test consumer:
  • apps/worker-workflow/src/cross-workflow/services/cross-workflow.consumer.spec.ts
  1. Unit test orchestrator:
  • apps/worker-workflow/src/cross-workflow/services/cross-workflow.service.spec.ts
  1. Unit test repository:
  • apps/worker-workflow/src/cross-workflow/repositories/cross-workflow.repository.spec.ts
  1. Typecheck worker-workflow:
  • pnpm exec tsc -p apps/worker-workflow/tsconfig.json --noEmit

8. Prompt Refactor (Siap Pakai)​

Refactor `apps/worker-workflow/src/cross-workflow` dengan aturan:
- pola consumer -> service -> repository
- query DB hanya di repository
- pisahkan behavior relation ONE_TO_MANY dan MANY_TO_ONE ke service berbeda
- jangan buat shared relation service besar
- create target saat koneksi kosong harus cek `wml_action.is_cr_trgt_empty_conn` dan log reason ketika skip
- pertahankan behavior runtime kecuali diminta

Setelah refactor:
1. update import path
2. jalankan test consumer + service + repository
3. jalankan typecheck worker-workflow
4. laporkan file yang dipindah/diubah dan risiko perubahan