Submission V2 System Behavior

1. System Behavior

1.1 Tujuan Context

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

Implementasi utama ada di:

• 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 snapshot workflow (SubmissionV2SnapshotService).
• Persistensi submission + sinkronisasi entity (SubmissionV2PersistenceService).
• Perhitungan approval snapshot + pembentukan log (SubmissionV2LogService).

Di luar scope context ini:

• Manajemen transaction boundary (caller yang membuat/commit/rollback QueryRunner).
• Publish event/message broker.
• HTTP cache clear Directus (dilakukan caller API, bukan SubmissionServiceV2).

2. Komponen Utama (kelas/fungsi + peran)

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

2. SubmissionV2SnapshotService Peran: resolve snapshot dari submission.workflowSnapshot atau load fresh dari tabel master workflow. Path: packages/lib/src/service/workflow-action/submission-v2/submission-v2-snapshot.service.ts

3. SubmissionV2PersistenceService Peran: operasi persistence submission/entity (lock row, create submission, update status, sync submission_id, sync native payload/status, resolve entity table). Path: packages/lib/src/service/workflow-action/submission-v2/submission-v2-persistence.service.ts

4. SubmissionV2LogService Peran: hitung snapshot approval 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 SubmissionServiceV2 dan dependency-nya. 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 urutan fallback: request.user.id -> payload.actor_user_id -> payload.actor_id -> 'system'.
3. Service validasi guard override: override=true hanya valid bila source='CROSS_WORKFLOW'.
4. Service mencari submission existing dengan lock pessimistic_write lewat findSubmissionForUpdate(...).
5. Service resolve snapshot workflow:

• pakai submission.workflowSnapshot jika sudah ada,
• jika kosong, load dari wml_workflow, wml_status, wml_action, wml_cross_wf_conn, wml_sla_policy.

6. Service validasi snapshot memuat workflow target (assertSnapshotHasWorkflow).
7. Service mencari action target di snapshot (findActionInSnapshotOrThrow) dan validasi action memang milik workflow tersebut.
8. Service validasi reason jika action mensyaratkan reason (isNeedReason/isReasonRequired).
9. Jika submission belum ada, service resolve entity reference (resolveEntity) lalu create row wxl_submission.
10. Service validasi action terhadap status submission saat ini (action.fromStatusId) kecuali override=true.
11. Jika submission existing belum punya entityId, service backfill entity reference (ensureSubmissionEntityRefIfMissing).
12. Service sync submission_id ke tabel entity target bila kolom submission_id tersedia.
13. Service persist workflow_snapshot ke wxl_submission jika sebelumnya kosong.
14. Service build approval snapshot + log payload, lalu insert wxl_submission_log.
15. Service update status submission (current_status_id, last_action_id) jika approval tidak required atau quorum sudah terpenuhi.
16. Service sync native entity:

• update status_id jika kolom ada,
• apply native_document_payload.payload yang kolomnya valid,
• apply action.entityPatchMapping.

17. Service return SetSubmissionResult (submission_id, status_from, status_to, action_id, snapshot approval, dan payload log).

4. Flowchart (Mermaid) -> minimal 1 diagram

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 (submitDefaultWorkflowV2)

2. Internal worker cross-workflow. Path:

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

3. Direct service call dari context lain yang sudah punya QueryRunner.

5.1 Contoh Pemakaian di Controller (API)

Contoh pemakaian pada endpoint API POST /api/workflow/submission/v2:

Controller:

@Post('submission/v2')
@ApiOperation({ summary: 'Submit workflow transition v2' })
async setSubmiision(@Body() body: SubmitWorkflowDtoV2) {
  const data = await this.workflowService.submitDefaultWorkflowV2(body);
  return data;
}

Service (transaction boundary + pemanggilan SubmissionServiceV2):

async submitDefaultWorkflowV2(body: any) {
  const queryRunner = this.dataSource.createQueryRunner();
  await queryRunner.connect();
  await queryRunner.startTransaction();

  try {
    const data = await this.submissionServiceV2.setSubmission(body, queryRunner);
    await queryRunner.commitTransaction();
    return data;
  } catch (error) {
    await queryRunner.rollbackTransaction();
    throw error;
  } finally {
    await queryRunner.release();
  }
}

Path implementasi:

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

5.2 Detail Input (tabel)

Definisi source type ada di 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 membuat submission baru.
workflow_id	string	Ya	Workflow target.
action_id	string	Ya	Action yang dieksekusi.
actor_id	string	Ya	Actor workflow.
actor_user_id	string	Tidak	User executor; fallback ke request user/actor_id.
reason_text	string	Kondisional	Wajib jika action membutuhkan reason.
override	boolean	Tidak	Bypass validasi fromStatusId; hanya boleh untuk source='CROSS_WORKFLOW'.
source	'ACTION' | 'CROSS_WORKFLOW'	Tidak	Menandai sumber trigger.
native_document_payload.path	string	Tidak	Harus match wml_workflow.entity bila diisi.
native_document_payload.payload	Record<string, unknown>	Tidak	Akan difilter sesuai kolom tabel entity yang valid.
do_not_clear_cache	boolean	Tidak	Dipakai caller API untuk skip clear cache setelah commit transaction.

Catatan:

• DTO API SubmitWorkflowDtoV2 saat ini mewajibkan native_document_payload. Path: apps/api/src/api/core/workflow/dtos/submit-workflow.payload.dto.ts

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

Side effect DB di transaction caller:

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

• workflow_snapshot (jika masih null),
• backfill entity/entity_id (jika kosong),
• update current_status_id + last_action_id (tergantung quorum approval).

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

• insert minimal row untuk generate entityId (saat create),
• update submission_id (jika kolom ada),
• update status_id (jika kolom ada),
• apply native payload valid + entityPatchMapping.

External call:

• Tidak ada external call langsung di SubmissionServiceV2 saat ini.
• Pada jalur API, WorkflowService.submitDefaultWorkflowV2 melakukan best-effort POST /utils/cache/clear via RestApiService setelah commit, kecuali do_not_clear_cache=true. Path: apps/api/src/api/core/workflow/workflow.service.ts

Event publish:

• Tidak ada publish event dari submission-v2.

6.1 Detail Output (tabel)

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

Property	Type	Keterangan
submission_id	string	ID submission final (existing/new).
status_from	string | null	Status asal.
status_to	string | null	Status tujuan; bisa null jika approval belum quorum.
action_id	string	Action yang diproses.
approval.required	boolean	Apakah action butuh approval.
approval.total_count	number	Target quorum.
approval.approved_count	number	Jumlah approval saat eksekusi ini.
approval.rejected_count	number	Jumlah reject saat eksekusi ini.
approval.quorum_met	boolean	Status quorum terpenuhi/tidak.
submission_log	Partial<WxlSubmissionLog>	Payload log yang diinsert ke wxl_submission_log.

7. Error Handling

Error utama melempar UnprocessableEntityException, antara lain:

1. Submission not found (submission id dikirim tapi row tidak ada).
2. override=true is allowed only for source=CROSS_WORKFLOW.
3. Reason is required for this action.
4. Workflow <id> not found in snapshot.
5. Action not found atau Action does not belong to workflow.
6. Invalid action for current status.
7. Mapping entity workflow invalid/missing (wml_workflow.entity).
8. native_document_payload.path tidak match entity workflow.
9. Payload native tidak memiliki kolom valid di tabel target.
10. Gagal create/sync entity atau sync submission_id.

Perilaku degradasi:

• Saat syncEntityStatus(...), jika yang gagal hanya sinkronisasi status tanpa native payload, service tidak throw; service log warning. Path: packages/lib/src/service/workflow-action/submission-v2/submission-v2-persistence.service.ts

8. Edge Cases

1. submission_id bernilai 'null' atau 'undefined' diperlakukan sebagai kosong.
2. Approval config dianggap invalid bila approval required tapi nilai quorum <= 0 atau bukan angka valid.
3. Approval langsung quorum_met=true jika target quorum <= 1.
4. Key native payload yang tidak ada di schema tabel akan di-drop dengan warning.
5. Jika semua key native payload tidak valid, service throw error.
6. Jika tabel entity tidak punya kolom submission_id, sinkronisasi link dilewati.
7. Jika tabel entity tidak punya kolom status_id, hanya payload/patch yang diupdate.
8. Jika entityPatchMapping berisi key yang tidak ada di tabel, potensi error ada di layer update DB.

9. Dependency & Integrasi

Dependency internal context:

1. TypeORM QueryRunner (wajib dari caller).
2. Entity workflow/submission:

• WmlWorkflow, WmlStatus, WmlAction, WmlCrossWfConn, WmlSlaPolicy
• WxlSubmission, WxlSubmissionLog

3. Request context REQUEST untuk actor resolution.

Integrasi eksternal context:

1. API workflow:

• apps/api/src/api/core/workflow/workflow.controller.ts
• apps/api/src/api/core/workflow/workflow.service.ts
• apps/api/src/api/core/workflow/dtos/submit-workflow.payload.dto.ts
• apps/api/src/api/core/workflow/workflow.submission-v2.integration.spec.ts

2. Worker cross-workflow:

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

3. Module registration:

• packages/lib/src/service/workflow-action/workflow-action.module.ts

10. Data Model yang relevan (ringkas, referensi ke ERD/entitas)

1. wxl_submission Entity: packages/lib/src/database/entities/wxl-submission.entity.ts

2. wxl_submission_log Entity: packages/lib/src/database/entities/wxl-submission-log.entity.ts

3. wml_workflow Entity: packages/lib/src/database/entities/wml-workflow.entity.ts

4. wml_action Entity: packages/lib/src/database/entities/wml-action.entity.ts

5. wml_status Entity: packages/lib/src/database/entities/wml-status.entity.ts

6. wml_cross_wf_conn Entity: packages/lib/src/database/entities/wml-cross-wf-conn.entity.ts

7. wml_sla_policy Entity: packages/lib/src/database/entities/wml-sla-policy.entity.ts

Referensi ERD workflow-action:

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

11. Referensi Kode (path file yang dipakai)

1. packages/lib/src/service/workflow-action/submission-v2/submission-v2.service.ts
2. packages/lib/src/service/workflow-action/submission-v2/submission-v2-persistence.service.ts
3. packages/lib/src/service/workflow-action/submission-v2/submission-v2-snapshot.service.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/workflow-action.module.ts
8. apps/api/src/api/core/workflow/workflow.controller.ts
9. apps/api/src/api/core/workflow/workflow.service.ts
10. apps/api/src/api/core/workflow/dtos/submit-workflow.payload.dto.ts
11. apps/api/src/api/core/workflow/workflow.submission-v2.integration.spec.ts
12. apps/worker-workflow/src/cross-workflow/services/cross-workflow.service.ts

12. Open Questions

1. SubmissionServiceV2 masih meng-inject CacheService, tetapi clear cache di service ini sudah tidak dieksekusi (kode clear cache di-comment). Perlu diputuskan apakah dependency ini tetap dipertahankan atau dihapus.
2. SubmitWorkflowDtoV2 belum memodelkan field service-level seperti reason_text, actor_user_id, override, source, dan do_not_clear_cache. Perlu diputuskan apakah field-field ini memang tidak boleh dari API atau DTO perlu diselaraskan.