Operational Units Module
Peruntukan: Dokumen ini khusus untuk Operational Unit (unit operasional: entity, region, zone, area, site, dll.). Konteks Organization Unit adalah modul terpisah — pastikan mengacu ke dokumen yang sesuai.
Overview
Operational Units Module mengelola struktur hierarki unit operasional dalam sistem: entity, region, zone, area, site, atau tipe operasional lain yang didefinisikan di master operation_unit_types.
Modul ini menjadi fondasi struktural untuk fitur enterprise seperti approval berjenjang, penugasan karyawan, kontrol akses berbasis struktur, dan reporting.
Hierarki diimplementasikan dengan materialized path (path disimpan per node), sehingga tree dapat di-query dan di-sort tanpa recursive CTE.
Goals
- Menyediakan single source of truth untuk struktur unit operasional
- Mendukung hierarki multi-level dengan aturan bisnis yang ketat (type-driven)
- Performa tinggi untuk operasi baca (listing & traversal)
- Integrasi lintas modul (HR, approval, authorization)
- Spesifikasi eksplisit untuk AI-driven code generation
Core Concepts
1. Hierarchy with Materialized Path
Setiap unit operasional memiliki kolom path yang menyimpan jalur dari root ke node.
- Segment length: 4 karakter
- Padding: zero-padded
- Separator:
.
Contoh:
0001.0003.0012
Makna:
- Setiap segmen = satu level hierarki
- Urutan segmen = posisi node dalam struktur
Keuntungan:
- Query tree tanpa recursive CTE
- Sorting hierarki natural (
ORDER BY path) - Performa tinggi untuk read-heavy
Detail algoritma (create root/child, move) ada di Technical Documentation (for_developer.md).
2. Type-Driven Hierarchy
Setiap unit memiliki type_key yang mengacu ke master operation_unit_types.
Contoh tipe (dari setup default):
| type_key | Level (contoh) | Contoh peran dalam hierarki |
|---|---|---|
| entity | 1 | Root (entitas/perusahaan) |
| region | 2 | Di bawah entity |
| zone | 3 | Di bawah region |
| area | 4 | Di bawah zone |
| site | 5 | Di bawah area (leaf) |
Aturan:
- Kompatibilitas parent–child mengikuti matriks type (level child > level parent)
- Validasi pada create dan move
Contoh:
- ✅ entity → region → zone → area → site
- ❌ region tidak boleh parent dari entity
- ❌ site tidak boleh punya child (jika didefinisikan sebagai leaf)
3. Ownership & Positions
- Owner (Employee): penanggung jawab unit, dengan
owner_orderuntuk prioritas - Job Position: posisi jabatan yang terkait dengan unit
Digunakan untuk approval berjenjang dan integrasi dengan HR.
Contoh Data Operational Unit
Contoh struktur dan format data (referensi: lania-master/bahan/setup-new-client/default-operational-unit.json).
Struktur hierarki (parent_code):
Entity (ENT-001) → Region (REG-001) → Zone (ZON-001) → Area (AR-001) → Site (SIT-001)
Format isian per record (flat array):
| Field | Keterangan | Contoh |
|---|---|---|
name | Nama unit operasional | "Default Entity" |
code | Kode unik (bisnis) | "ENT-001" |
type_key | Tipe dari master | "entity", "region", "zone", "area", "site" |
parent_code | Kode parent (null = root) | null atau "ENT-001" |
is_active | Status aktif | true |
Contoh payload (flat list):
[
{"name":"Default Entity","code":"ENT-001","type_key":"entity","parent_code":null,"is_active":true},
{"name":"Default Region","code":"REG-001","type_key":"region","parent_code":"ENT-001","is_active":true},
{"name":"Default Zone","code":"ZON-001","type_key":"zone","parent_code":"REG-001","is_active":true},
{"name":"Default Area","code":"AR-001","type_key":"area","parent_code":"ZON-001","is_active":true},
{"name":"Default Site","code":"SIT-001","type_key":"site","parent_code":"AR-001","is_active":true}
]
API create biasanya per unit (POST body per node); parent_id (UUID) dipakai setelah unit parent ada. Untuk bulk setup, urutan insert harus dari root ke leaf agar parent_id tersedia.
Supported Operations
| Operasi | Intent / Ringkasan |
|---|---|
| Create | Buat unit (root atau child); path di-generate otomatis |
| List | Daftar flat atau tree (tree, type_key, include_inactive, search, pagination) |
| Detail | Get by id (termasuk owners, positions) |
| Update | Update atribut (name, code, type_key, is_active) |
| Move | Ubah parent dan rekalkulasi path (subtree ikut) |
| Assign/Remove owner | Tambah/hapus owner (employee) dengan optional owner_order |
| Assign/Remove position | Tambah/hapus job position |
| Toggle active | Activate/deactivate (harus tidak ada child/owner/position aktif) |
| Soft delete | Nonaktifkan dan tandai deleted (harus sudah inactive, children kosong) |
| Hard delete | Hapus permanen (harus sudah soft-deleted, tidak ada referensi) |
Kontrak API detail (route, payload, response) ada di operational-units.mcp.json dan technical doc.
Data Integrity Rules
- Tidak ada circular reference (parent bukan descendant dari node saat ini)
- Kompatibilitas tipe parent–child sesuai matriks type
- Move: parent baru bukan descendant; kedua node aktif
- Deactivate: tidak boleh jika masih ada child/owner/position aktif
- Soft delete: hanya jika unit sudah inactive dan tidak ada child aktif
- Hard delete: hanya setelah soft delete dan tidak ada foreign reference
- Urutan owner konsisten (no gaps)
Error Codes (Ringkasan)
| Code | HTTP | Deskripsi singkat |
|---|---|---|
| CIRCULAR_REFERENCE | 422 | Parent adalah descendant dari unit saat ini |
| TYPE_INCOMPATIBLE | 422 | Tipe parent–child tidak diizinkan |
| UNIT_INACTIVE | 409 | Unit tidak aktif |
| HAS_ACTIVE_CHILDREN | 409 | Masih ada child aktif |
| HAS_ACTIVE_OWNERS | 409 | Masih ada owner aktif |
| HAS_ACTIVE_POSITIONS | 409 | Masih ada position aktif |
| SOFT_DELETE_REQUIRED | 409 | Harus soft-delete dulu sebelum hard delete |
| RELATED_RECORD_EXISTS | 409 | Ada record terkait yang menghalangi penghapusan |
| NOT_FOUND | 404 | Operational unit tidak ditemukan |
Detail response shape dan pesan ada di for_developer.md.
Events
Event dipublikasikan setelah transaction commit.
| Event | Trigger |
|---|---|
| operation_unit.created | Setelah create sukses |
| operation_unit.updated | Update atribut |
| operation_unit.moved | Perubahan parent/path |
| operation_unit.activated | is_active = true |
| operation_unit.deactivated | is_active = false |
| operation_unit.deleted | Soft delete |
Payload contoh dan key ada di for_developer.md dan operational-units.mcp.json.
Integrasi (Cross-Module)
| Modul | Tujuan integrasi | Tipe dependency |
|---|---|---|
| Employees | Assign owners ke unit | Foreign key |
| Job Positions | Assign positions ke unit | Foreign key |
| Approval Engine | Approval berjenjang | Read-only |
| Authorization | Scope & access control | Read-only |
| Reporting | Agregasi per hierarki | Read-only |
Technical Characteristics
- Identifier: UUID
- Hierarki: materialized path (segment 4 char, zero-padded)
- API base:
/Operational-units(lihat MCP untuk detail) - Tree traversal tanpa recursive query di application layer
- Siap REST API & OpenAPI
- Row-Level Security (RLS) untuk tenant isolation — gunakan tenant-scoped client; detail di for_developer.md
Typical Use Cases
- Struktur wilayah operasional: Entity → Region → Zone → Area → Site
- Approval chain berbasis unit operasional
- Pembagian tanggung jawab dan otorisasi (owners, positions)
- Reporting dan agregasi berbasis hierarki
- Kontrol akses berdasarkan scope unit
Referensi untuk Implementasi
- Technical Documentation (algoritma, error, event, integrasi, testing):
for_developer.md - Kontrak API & policy machine-readable:
operational-units.mcp.json - Contoh data setup:
lania-master/bahan/setup-new-client/default-operational-unit.json
Summary
Operational Units Module adalah modul fondasional untuk struktur hierarki unit operasional (entity, region, zone, area, site, dll.) dengan materialized path, type-driven hierarchy, dan aturan integritas yang ketat. Cocok untuk sistem enterprise yang butuh performa tinggi, integritas data, dan integrasi lintas modul maupun AI-driven automation. Untuk detail teknis dan kontrak API, gunakan for_developer.md dan operational-units.mcp.json.