Organization Units Module

Peruntukan dokumen ini: Halaman ini khusus untuk Organization Unit (unit organisasi). Konteks Operational Unit merupakan modul/konteks terpisah dan didokumentasikan di tempat lain. Pastikan Anda mengacu ke dokumen yang sesuai sesuai kebutuhan.

Overview

Organization Units Module adalah modul inti yang bertanggung jawab untuk mengelola struktur hierarki unit organisasi dalam sistem, seperti directorate, division, department, section, unit, atau struktur organisasi perusahaan lainnya.

Modul ini dirancang sebagai fondasi struktural bagi berbagai fitur enterprise, termasuk approval berjenjang, assignment karyawan, kontrol akses berbasis struktur, module provisioning, serta reporting dan analitik.

Hierarki unit diimplementasikan menggunakan pendekatan PostgreSQL ltree extension, yang memungkinkan query struktur tree secara efisien dengan performa tinggi untuk operasi read-heavy.

Goals

Tujuan utama dari modul ini adalah:

Menyediakan single source of truth untuk struktur unit organisasi
Mendukung hierarki multi-level dengan aturan bisnis yang ketat (type-driven hierarchy)
Memastikan performa tinggi untuk operasi baca (listing & traversal)
Menjadi basis integrasi lintas modul (HR, approval, authorization, module provisioning)
Mendukung auto-tag creation untuk memudahkan kategorisasi dan pencarian
Mendukung AI-driven code generation melalui spesifikasi yang eksplisit

Core Concepts

1. Hierarchy with PostgreSQL Ltree

Setiap unit organisasi memiliki kolom path_ltree yang menyimpan jalur lengkap dari root ke node tersebut menggunakan PostgreSQL ltree extension.

Contoh:

uuid_a.uuid_b.uuid_c

Displayed as:

0001.0002.0003

Makna:

Setiap segmen merepresentasikan satu level hierarki (UUID-based)
Separator . memisahkan level-level dalam path
Urutan segmen menunjukkan posisi node dalam struktur

Keuntungan pendekatan ini:

Query tree tanpa recursive CTE (menggunakan ltree operators)
Fast descendant/ancestor queries dengan GiST index
Performa tinggi untuk sistem read-heavy
Native PostgreSQL support dengan operator rich

2. Type-Driven Hierarchy

Setiap unit organisasi memiliki atribut type_key yang mengacu ke master core_organization_unit_types.

Setiap type memiliki level_order yang menentukan urutan hierarki. Contoh type organization unit (dari master core_organization_unit_types):

Directorate (level_order: 1)
Division (level_order: 2)
Department (level_order: 3)
Section (level_order: 4)
Unit (level_order: 5)

Aturan kompatibilitas antar tipe memastikan bahwa:

Tidak semua tipe dapat menjadi parent dari tipe lain
Struktur organisasi tetap valid secara bisnis
Child type level MUST be higher than parent type level

Contoh:

✅ directorate (level 1) → dapat menampung division (level 2)
✅ division (level 2) → dapat menampung department (level 3)
✅ department (level 3) → dapat menampung section (level 4)
✅ section (level 4) → dapat menampung unit (level 5)
❌ division (level 2) → tidak dapat menampung directorate (level 1)
❌ department (level 3) → tidak dapat menampung department (level 3) — same level

Aturan ini divalidasi pada saat:

Create unit
Update unit (jika type atau parent berubah)

Modul ini mendukung penugasan dan asosiasi data terkait:

Owners (Employee) - Penanggung jawab unit dengan owner_order untuk prioritas
Modules - Module availability dengan default role provisioning
Information - Contact details, legal info, timezone
Tags - Categorization tags (auto-created dari name, short_name, code, type_key)
Documents - File attachments
Banks - Associated company bank accounts

Fungsi utama fitur ini:

Menentukan penanggung jawab unit (owners)
Module provisioning berdasarkan unit
Kontrol akses berbasis struktur organisasi
Integrasi dengan struktur HR dan keuangan
Pencarian dan filtering dengan tags

Contoh Data Organization Unit

Contoh struktur dan format data organization unit (referensi: lania-master/bahan/setup-new-client/default-organization-unit.json):

Struktur hierarki contoh:

Direktorat Operasional (directorate)
└── Divisi Supply Chain (division)
    ├── Department Pengadaan (department)
    │   ├── Section Vendor Management (section)
    │   │   └── Unit Evaluasi Vendor (unit)
    │   └── Section Purchasing (section)
    ├── Department Logistik (department)
    │   ├── Section Transportasi (section)
    │   └── Section Pergudangan (section)
    └── Department Manajemen Persediaan (department)
        └── Section Kontrol Stok (section)
Direktorat Keuangan (directorate)
└── Divisi Keuangan (division)
    ├── Department Akuntansi (department)
    └── Department Treasury (department)
... (Direktorat SDM, Direktorat Penjualan & Pemasaran, dsb.)

Format isian per node (untuk create/bulk setup):

Field	Keterangan	Contoh
`name`	Nama lengkap organization unit	`"Direktorat Operasional"`
`short_name`	Nama singkat	`"DirOps"`
`code`	Kode unit (unik/bisnis)	`"DIR-OPS"`
`type_key`	Tipe dari master (sesuai level)	`"directorate"`, `"division"`, `"department"`, `"section"`, `"unit"`
`is_active`	Status aktif	`true`
`children`	Array child (untuk nested payload)	`[]` atau array node

Contoh satu node dengan children (JSON):

{
  "name": "Direktorat Operasional",
  "short_name": "DirOps",
  "code": "DIR-OPS",
  "type_key": "directorate",
  "is_active": true,
  "children": [
    {
      "name": "Divisi Supply Chain",
      "short_name": "DivSupply",
      "code": "DIV-SUPPLY",
      "type_key": "division",
      "is_active": true,
      "children": [
        {
          "name": "Department Pengadaan",
          "short_name": "Procurement",
          "code": "DEPT-PROC",
          "type_key": "department",
          "is_active": true,
          "children": []
        }
      ]
    }
  ]
}

Data di atas adalah khusus organization unit; untuk operational unit gunakan sumber/contoh data yang sesuai modul operational unit.

Supported Operations

Organization Units Module menyediakan lifecycle lengkap untuk unit organisasi:

Create unit (root atau child) dengan auto-tag creation
List unit (flat atau tree dengan table_tree parameter)
Get detail unit dengan semua related data
Update unit attributes (partial update)
Update parent (move dalam hierarki)
Toggle active status (dengan validasi children)
Soft delete (set is_active = false)
Hard delete (permanent delete, setelah soft delete)

Setiap operasi dilengkapi dengan:

Validasi eksplisit dengan error codes yang jelas
Aturan bisnis machine-readable
Proteksi terhadap pelanggaran integritas data
Comprehensive error handling dengan reason field

Data Integrity Rules

Untuk menjaga konsistensi dan keandalan data, modul ini menegakkan aturan berikut:

Mencegah circular reference pada hierarki (self, descendant)
Validasi kompatibilitas tipe parent–child (type level hierarchy)
Parent harus exist dan active
Larangan menghapus unit yang masih memiliki child aktif
Larangan mengubah parent menjadi descendant
Larangan menonaktifkan unit yang masih memiliki dependensi aktif
Auto-tag creation untuk memudahkan kategorisasi

Auto-Tag Creation

Ketika create organization unit, sistem otomatis membuat tags dari:

name - Nama organization unit
short_name - Short name (jika berbeda dari name)
code - Code organization unit (jika ada)
type_key - Type organization unit

Behavior:

Tags dibuat di table organization_unit_tags dengan slug auto-generated
Jika tag dengan slug yang sama sudah ada, akan menggunakan tag existing
Tags otomatis di-associate dengan organization unit via organization_unit_has_tag
Duplicate tags tidak akan dibuat (berdasarkan slug)

Example:

POST /organization-units
{
  "name": "Direktorat Operasional",
  "short_name": "DirOps",
  "code": "DIR-OPS",
  "type_key": "directorate",
  ...
}

Auto-created tags:

Tag: "Direktorat Operasional" (slug: "direktorat-operasional")
Tag: "DirOps" (slug: "dirops")
Tag: "DIR-OPS" (slug: "dir-ops")
Tag: "directorate" (slug: "directorate")

Semua tags di atas otomatis ter-associate dengan organization unit yang baru dibuat.

Technical Characteristics

Identifier menggunakan UUID
Hierarki berbasis PostgreSQL ltree extension
Tree traversal tanpa recursive query (menggunakan ltree operators)
CQRS Pattern - Separation of Commands (write) and Queries (read)
Auto-tag creation untuk kategorisasi otomatis
Siap untuk REST API dan OpenAPI generation
Cocok untuk sistem enterprise dengan struktur kompleks
Row-Level Security (RLS) untuk tenant isolation

Typical Use Cases

Struktur organisasi perusahaan (Directorate → Division → Department → Section → Unit)
Module provisioning berdasarkan struktur organisasi
Approval chain berbasis unit
Pembagian tanggung jawab dan otorisasi (owners)
Kontrol akses berbasis struktur
Reporting berbasis hierarki
Tag-based search dan filtering
Bank account association per unit

Architecture

Module ini mengikuti CQRS (Command Query Responsibility Segregation) pattern:

┌─────────────────┐
│   Controller    │  ← REST API Layer
└────────┬────────┘
         │
┌────────▼────────┐
│    Service      │  ← Orchestration Layer (thin, delegates to commands/queries)
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
┌───▼───┐ ┌──▼────┐
│Queries│ │Commands│  ← Business Logic Layer
└───┬───┘ └──┬────┘
    │        │
    └────┬───┘
         │
    ┌────▼────┐
    │Validator│  ← Validation Layer
    └────┬────┘
         │
    ┌────▼────┐
    │ Mapper  │  ← Data Transformation Layer
    └────┬────┘
         │
    ┌────▼────┐
    │ Prisma  │  ← Data Access Layer
    └─────────┘

Benefits:

Separation of Concerns - Read dan write logic jelas terpisah
Single Responsibility - Setiap command/query menangani satu operasi
DRY Principle - Shared mapper menghilangkan duplikasi code
Testability - Mudah untuk unit test komponen individual
Scalability - Mudah menambah operasi baru tanpa membesarkan service

Summary

Organization Units Module adalah modul fondasional yang menangani struktur hierarki organization unit (bukan operational unit) secara eksplisit, scalable, dan konsisten. Dengan pendekatan PostgreSQL ltree, type-driven hierarchy, dan aturan bisnis yang ketat, modul ini sangat cocok untuk sistem enterprise yang membutuhkan performa tinggi, integritas data, auto-tagging, dan kemudahan integrasi lintas modul maupun AI-driven automation.

Key Features:

PostgreSQL ltree untuk performa tinggi
Type-driven hierarchy dengan validasi level
Auto-tag creation untuk kategorisasi
CQRS pattern untuk separation of concerns
Comprehensive validation dengan error codes
Rich related data (modules, information, owners, tags, documents, banks)

Overview​

Goals​

Core Concepts​

1. Hierarchy with PostgreSQL Ltree​

2. Type-Driven Hierarchy​

3. Ownership & Related Data​

Contoh Data Organization Unit​

Supported Operations​

Data Integrity Rules​

Auto-Tag Creation​

Technical Characteristics​

Typical Use Cases​

Architecture​

Summary​