Submission V2 System Behavior

1. System Behavior

1.1 Tujuan Context

Context submission-v2 menjalankan transisi workflow berbasis action untuk satu submission, meliputi validasi guard, pembuatan log, update status submission, dan sinkronisasi data ke tabel entity native.

Implementasi utama:

• packages/lib/src/service/workflow-action/submission-v2/submission-v2.service.ts

1.2 Scope

Termasuk dalam scope context ini:

• Orkestrasi setSubmission(...) di SubmissionServiceV2.
• Resolusi data workflow/action/submission dari tabel live via repository.
• Persistensi submission/entity via command repository.
• Perhitungan approval snapshot + pembentukan payload log.

Di luar scope context ini:

• Boundary transaksi (dibuat oleh caller yang mengelola QueryRunner).
• Publish event/message broker.
• HTTP cache clear di layer API.

2. Komponen Utama (kelas/fungsi + peran)

1. SubmissionServiceV2.setSubmission(payload, queryRunner) Peran: orkestrator flow submission-v2. Path: packages/lib/src/service/workflow-action/submission-v2/submission-v2.service.ts

2. SubmissionV2Repository Peran: read-query data live (wxl_submission, wml_workflow, wml_action). Path: packages/lib/src/service/workflow-action/submission-v2/submission-v2.repository.ts

3. SubmissionV2CommandRepository Peran: command/write ke wxl_submission, wxl_submission_log, dan tabel entity native. Path: packages/lib/src/service/workflow-action/submission-v2/submission-v2-command.repository.ts

4. SubmissionV2LogService Peran: hitung approval snapshot dan build payload log wxl_submission_log. Path: packages/lib/src/service/workflow-action/submission-v2/submission-v2-log.service.ts

5. WorkflowActionModule Peran: registrasi provider submission-v2. Path: packages/lib/src/service/workflow-action/workflow-action.module.ts

3. Alur System Behavior (happy path, step-by-step)

1. Caller memanggil SubmissionServiceV2.setSubmission(payload, queryRunner).
2. Service resolve actorUserId dari fallback: request.user.id -> payload.actor_user_id -> DEFAULT_FALLBACK_USER_ID.
3. Service validasi guard override: override=true hanya valid untuk source='CROSS_WORKFLOW'.
4. Service ambil submission existing via SubmissionV2Repository.findSubmissionForUpdate(...) (lock pessimistic_write).
5. Service ambil workflow live via SubmissionV2Repository.findWorkflowById(...).
6. Service ambil action live via SubmissionV2Repository.findActionById(...).
7. Service validasi:

• workflow ada,
• action ada,
• action milik workflow yang sama,
• submission existing (jika ada) milik workflow yang sama.

8. Service validasi reason jika action mensyaratkan reason.
9. Jika submission belum ada, service resolve entity (resolveEntity) lalu create row wxl_submission.
10. Service validasi fromStatus terhadap status submission saat ini (kecuali override=true).
11. Jika submission existing belum punya entityId, service backfill entity reference.
12. Service sinkronkan submission_id ke tabel entity bila kolom tersedia.
13. Service hitung approval snapshot + build payload log.
14. Service insert wxl_submission_log.
15. Service update status submission (current_status_id, last_action_id) jika approval tidak pending.
16. Service sinkronkan status/native payload/entityPatchMapping ke tabel entity native.
17. Service return SetSubmissionResult.

4. Flowchart (Mermaid)

5. Trigger & Input (API/event/scheduler + payload penting)

Trigger utama yang memanggil setSubmission(...):

1. API endpoint POST /api/workflow/submission/v2. Path:

• apps/api/src/api/core/workflow/workflow.controller.ts
• apps/api/src/api/core/workflow/workflow.service.ts

2. Worker cross-workflow. Path:

• apps/worker-workflow/src/cross-workflow/services/cross-workflow-one-to-many.service.ts
• apps/worker-workflow/src/cross-workflow/services/cross-workflow-many-to-one.service.ts

5.1 Detail Input (tabel)

Definisi type: packages/lib/src/service/workflow-action/submission-v2/submission-v2.types.ts

Property	Type	Wajib	Keterangan
submission_id	string | null	Tidak	Jika kosong/null/"null"/"undefined", service create submission baru.
entity_id	string | null	Tidak	Dipakai untuk pakai row entity existing saat create/backfill.
workflow_id	string	Ya	Workflow target.
action_id	string	Ya	Action yang dieksekusi.
actor_id	string | null	Tidak	Actor workflow (opsional).
actor_user_id	string	Tidak	User executor; fallback ke request user/default.
reason_text	string	Kondisional	Wajib jika action mensyaratkan reason.
override	boolean	Tidak	Bypass validasi status asal; hanya boleh untuk source cross-workflow.
source	'ACTION' | 'CROSS_WORKFLOW'	Tidak	Sumber trigger.
native_document_payload.path	string	Tidak	Harus match wml_workflow.entity jika diisi.
native_document_payload.payload	Record<string, unknown>	Tidak	Akan difilter sesuai kolom valid tabel entity.
do_not_clear_cache	boolean	Tidak	Saat ini tidak dipakai di SubmissionServiceV2 (pass-through compatibility).

6. Output & Side Effects (DB update, publish event, external call)

Side effect DB dalam transaksi caller:

1. Insert wxl_submission (jika create baru).
2. Update wxl_submission untuk:

• backfill entity/entity_id jika kosong,
• update current_status_id + last_action_id jika quorum terpenuhi.

3. Insert wxl_submission_log.
4. Insert/Update tabel entity native:

• create row minimal saat butuh generate entity id,
• update submission_id jika kolom ada,
• update status_id jika kolom ada,
• apply native payload valid dan entityPatchMapping.

6.1 Detail Output (tabel)

Definisi return type: packages/lib/src/service/workflow-action/submission-v2/submission-v2.types.ts

Property	Type	Keterangan
submission_id	string	ID submission final.
status_from	string | null	Status asal.
status_to	string | null	Status tujuan (bisa null jika approval masih pending).
action_id	string	Action yang dieksekusi.
approval.required	boolean	Action butuh approval atau tidak.
approval.total_count	number	Target quorum approval.
approval.approved_count	number	Approval count saat eksekusi ini.
approval.rejected_count	number	Rejected count saat eksekusi ini.
approval.quorum_met	boolean	Quorum terpenuhi atau tidak.
submission_log	Partial<WxlSubmissionLog>	Payload log yang disimpan.

7. Error Handling

Error utama (UnprocessableEntityException):

1. Submission not found.
2. override=true is allowed only for source=CROSS_WORKFLOW.
3. Workflow <id> not found.
4. Action not found.
5. Action does not belong to workflow.
6. Submission does not belong to workflow.
7. Reason is required for this action.
8. Invalid action for current status.
9. Validasi entity/native payload gagal.
10. Insert/update entity native gagal.

Perilaku degradasi:

• syncEntityStatus(...) bisa warning-only jika gagal sinkronisasi status tanpa native payload.

8. Edge Cases

1. submission_id string 'null' / 'undefined' dianggap kosong.
2. Approval config invalid (required tapi quorum <= 0) akan throw.
3. ANY_ONE dengan quorum 1 langsung quorum_met=true.
4. Key native payload yang tidak ada di schema tabel akan di-drop.
5. Jika semua key payload ter-drop, service throw error.
6. Jika tabel entity tidak punya kolom submission_id, sinkronisasi link dilewati.
7. Jika tabel entity tidak punya kolom status_id, update status dilewati.

9. Dependency & Integrasi

Dependency internal:

1. QueryRunner dari caller.
2. SubmissionV2Repository (read).
3. SubmissionV2CommandRepository (write).
4. SubmissionV2LogService.

Integrasi eksternal:

1. API workflow (apps/api/src/api/core/workflow/*).
2. Worker cross-workflow (apps/worker-workflow/src/cross-workflow/services/*).

10. Data Model Relevan

1. wxl_submission -> packages/lib/src/database/entities/wxl-submission.entity.ts
2. wxl_submission_log -> packages/lib/src/database/entities/wxl-submission-log.entity.ts
3. wml_workflow -> packages/lib/src/database/entities/wml-workflow.entity.ts
4. wml_action -> packages/lib/src/database/entities/wml-action.entity.ts

Referensi ERD:

• packages/lib/src/service/workflow-action/docs/erd.md

11. Referensi Kode

1. packages/lib/src/service/workflow-action/submission-v2/submission-v2.service.ts
2. packages/lib/src/service/workflow-action/submission-v2/submission-v2.repository.ts
3. packages/lib/src/service/workflow-action/submission-v2/submission-v2-command.repository.ts
4. packages/lib/src/service/workflow-action/submission-v2/submission-v2-log.service.ts
5. packages/lib/src/service/workflow-action/submission-v2/submission-v2.types.ts
6. packages/lib/src/service/workflow-action/submission-v2/submission-v2.service.spec.ts
7. packages/lib/src/service/workflow-action/submission-v2/submission-v2.repository.spec.ts
8. packages/lib/src/service/workflow-action/workflow-action.module.ts

12. Open Questions

1. do_not_clear_cache masih ada di kontrak payload, tetapi saat ini tidak dipakai di SubmissionServiceV2. Perlu diputuskan tetap dipertahankan atau didepresiasi.