Locations Module

Version: 1.0
Last Updated: Februari 2025
Status: Implemented

---

1. Executive Summary

1.1 Overview

Locations Module adalah modul manajemen lokasi dengan dukungan struktur hierarkis (parent-child). Lokasi digunakan untuk mengorganisir aset fisik maupun logis perusahaan (gudang, kantor cabang, area penyimpanan, rak, dll.) dalam struktur tree. Setiap lokasi terhubung ke Organization Unit (branch) dan dapat memiliki policies yang mengatur kemampuan operasional lokasi tersebut.

1.2 Problem Statement

Perusahaan perlu sistem untuk:

• Mengelola lokasi fisik/logis dalam struktur hierarkis yang fleksibel
• Menjamin integritas hierarki (tanpa circular reference, type hierarchy valid)
• Mengatur kemampuan operasional per lokasi (inventory, transfer, sales, dll.)
• Mendukung multi-tenant dengan isolasi data per tenant

1.3 Target Users

Persona	Role	Use Cases
Admin/Setup	HR/Admin, IT Setup	Create location structure, configure policies
Operations	Warehouse Manager, Branch Manager	Manage locations, move/reassign, toggle status
Finance/Reporting	Finance Team	View location tree, usage stats
Integration	System/Backend	Consume locations API untuk modul lain (inventory, sales, dll.)

---

2. Goals & Objectives

2.1 Business Goals

• Memungkinkan organisasi mendefinisikan struktur lokasi yang sesuai bisnis (warehouse → area → rack → shelf)
• Mendukung operasional harian: create, update, move, deactivate lokasi
• Memastikan data konsisten dan integritas hierarki terjaga
• Menyediakan basis data lokasi untuk integrasi dengan modul inventory, sales, procurement, dll.

2.2 Product Objectives

1. CRUD Locations — User dapat create, read, update lokasi dengan validasi ketat
2. Hierarchy Management — Support parent-child, move, type hierarchy rules
3. Policy Assignment — Assign policies ke lokasi (terpisah dari create/update)
4. Meta/Reference Data — Categories, types, policies tersedia untuk dropdown/select
5. Audit & Usage — History perubahan dan statistik penggunaan

---

3. User Stories

3.1 Location CRUD

ID	User Story	Acceptance Criteria
US-01	Sebagai Admin, saya ingin membuat lokasi baru agar dapat mendaftarkan gudang/kantor baru	Lokasi tersimpan dengan org_unit, type, category, code unik; parent opsional; hierarchy valid
US-02	Sebagai Admin, saya ingin melihat daftar lokasi dengan filter agar dapat menemukan lokasi tertentu	List dengan filter org_unit, type, category, search; pagination; mode tree
US-03	Sebagai Admin, saya ingin melihat detail lokasi agar dapat memeriksa info lengkap	Detail termasuk parent, children count, information, attributes
US-04	Sebagai Admin, saya ingin update lokasi agar dapat koreksi data	Partial update; validasi circular reference & hierarchy
US-05	Sebagai Admin, saya ingin soft delete lokasi agar data tidak hilang	is_active = false; tidak bisa jika punya active children atau inventory

3.2 Hierarchy

ID	User Story	Acceptance Criteria
US-06	Sebagai Admin, saya ingin memindahkan lokasi ke parent lain agar struktur dapat diubah	Move berhasil; path_ltree terupdate; tidak boleh circular
US-07	Sebagai Admin, saya ingin melihat children lokasi agar tahu struktur bawahnya	Return direct children only
US-08	Sebagai Admin, saya ingin melihat parents lokasi agar tahu chain ke root	Return all parents dari root ke direct parent
US-09	Sebagai Admin, saya ingin toggle status lokasi agar bisa deactivate	Tidak bisa deactivate jika ada active children

3.3 Policies

ID	User Story	Acceptance Criteria
US-10	Sebagai Admin, saya ingin melihat policies lokasi agar tahu kemampuan operasional	List policy key, name, group_name
US-11	Sebagai Admin, saya ingin set policies lokasi agar mengatur kemampuan	Replace all policies; validasi policy key ada di core
US-12	Sebagai Admin, saya ingin sync policies dari mappings agar cepat apply default	Policies diganti sesuai core_location_policy_mappings (category+type)
US-13	Sebagai Admin, saya ingin melihat daftar semua policies (meta) agar bisa pilih saat set	List dari core_location_policy; read-only

3.4 Utility & Meta

ID	User Story	Acceptance Criteria
US-14	Sebagai User, saya ingin search lokasi cepat agar dapat autocomplete/typeahead	Search by name, code, short_name; limit hasil
US-15	Sebagai User, saya ingin melihat usage lokasi (inventory count, child count)	Return statistics
US-16	Sebagai User, saya ingin melihat audit history lokasi	Paginated history dari lania-common
US-17	Sebagai User, saya ingin melihat categories, types (meta) untuk form	List categories, types (filter by category), type detail, attributes schema
US-18	Sebagai Admin, saya ingin bulk create lokasi agar efisien	Create banyak lokasi; return success/failed per item
US-19	Sebagai User, saya ingin validasi parent sebelum create agar tidak salah	Endpoint validate-parent
US-20	Sebagai User, saya ingin validasi attributes sebelum submit	Endpoint validate-attributes

---

4. Functional Requirements

4.1 Core Features

FR-01: Create Location

• Input: org_unit_id, location_type_key, category_key, name, code, is_active (required); parent_location_id, short_name, address, coordinates, attributes (optional)
• Validation: Org unit exists; type exists; parent exists & active (if provided); type hierarchy valid; code unique in org_unit
• Output: Location object dengan id, timestamps

FR-02: List Locations

• Input: Query params: search, org_unit_id, op_unit_id, location_type_key[], category_key, parent_location_id, table_tree, is_active, order_by, order_direction, page, limit
• Output: Paginated list atau tree structure (subRows)

FR-03: Get Location Detail

• Input: location id (path)
• Output: Full detail termasuk relations (parent, type, information, owners, documents, tags)

FR-04: Update Location

• Input: location id; body partial (semua optional)
• Validation: Circular reference check; hierarchy re-validation; code uniqueness
• Output: Updated location

FR-05: Soft Delete Location

• Validation: No active children; no inventory
• Action: Set is_active = false

FR-06: Hard Delete Location

• Validation: No children; must be soft-deleted first
• Action: Permanent delete

FR-07: Move Location

• Input: location id; new_parent_id (query)
• Validation: New parent exists & active; not self; not descendant; type hierarchy valid
• Output: Updated location (path recalculated)

FR-08: Toggle Status

• Validation: Cannot deactivate if has active children
• Action: Toggle is_active

FR-09: Get/Set/Sync Policies

• Get: Return policies assigned to location
• Set: Replace policies; validate all keys exist in core_location_policy
• Sync: Replace with policies from core_location_policy_mappings (by category+type)

FR-10: Meta Endpoints

• List categories, types, type detail, type attributes, policies
• Policies adalah core data (read-only, di-seed)

4.2 Hierarchy Rules

Rule	Description	Enforcement
Type Hierarchy	Child type level MUST be higher than parent type level	Create, Update, Move
No Self Reference	Location cannot be its own parent	Update, Move
No Circular Reference	Cannot set parent to a descendant	Update, Move
Code Uniqueness	Code must be unique within same org_unit	Create, Update
Active Children	Cannot deactivate if has active children	Toggle Status, Soft Delete
No Children for Hard Delete	Must remove all children first	Hard Delete

---

5. Non-Functional Requirements

5.1 Security

• Semua endpoint require authentication (Bearer token)
• Tenant isolation: data filtered by tenant_id (X-LANYA-TID)
• Core tables (categories, types, policies) shared; tenant tables (locations) isolated

5.2 Performance

• Pagination default 20 items
• Tree mode: return all (no pagination) — consider limit for very large trees
• LTree index untuk query hierarchy efisien
• Search dengan limit default 10

5.3 Data Integrity

• Soft delete default; hard delete hanya untuk cleanup
• Audit trail ke lania-common untuk create, update, delete, hard delete
• Policy history table (LocationPolicyHistory) untuk tracking perubahan policies

5.4 Compatibility

• UUID v4 untuk semua ID
• ISO 8601 untuk timestamps
• JSON untuk attributes (flexible schema per type)

---

6. Business Rules Summary

6.1 Location Lifecycle

1. Create → Active
2. Toggle Status → Active/Inactive
3. Soft Delete → is_active = false (reversible)
4. Hard Delete → Permanent (irreversible)

6.2 Constraints

• Lokasi harus punya org_unit (branch)
• Lokasi harus punya type yang valid
• Child type level > parent type level
• Code unique per org_unit
• Policies tidak di-set saat create; manage terpisah

6.3 Core Data (Read-Only)

• Categories (core_location_categories)
• Types (core_location_types)
• Policies (core_location_policy)
• Policy Mappings (core_location_policy_mappings)
• Attribute Definitions & Mappings

Data core di-seed dari JSON; user tidak bisa CRUD.

---

7. Out of Scope (Current Version)

• Geographic/map visualization
• Import/Export locations
• Location cloning/duplication
• Custom attributes CRUD (schema fixed per type)
• Location templates
• Bulk move/update
• Location-level permissions (selain policies)
• Inventory integration logic (hanya usage count)

---

8. Success Metrics

Metric	Target	Measurement
API Availability	99.9%	Uptime monitoring
Create/Update Latency	< 500ms	P95 response time
Tree Query (100 nodes)	< 1s	P95 response time
Zero Data Integrity Violations	100%	No circular ref, invalid hierarchy in prod

---

9. Appendix

9.1 API Endpoint Summary

Method	Endpoint	Description
POST	/locations	Create location
GET	/locations	List locations (filter, pagination, tree)
GET	/locations/tree	Tree structure alias
GET	/locations/search	Quick search
GET	/locations/:id	Get detail
GET	/locations/:id/children	Get children
GET	/locations/:id/parents	Get parents
GET	/locations/:id/usage	Usage stats
GET	/locations/:id/policies	Get policies
PUT	/locations/:id	Update location
PUT	/locations/:id/policies	Set policies
POST	/locations/:id/policies/sync	Sync policies
PATCH	/locations/:id/status	Toggle status
POST	/locations/:id/move	Move location
DELETE	/locations/:id	Soft delete
DELETE	/locations/hard-delete/:id	Hard delete
POST	/locations/bulk	Bulk create
POST	/locations/validate-parent	Validate parent
POST	/locations/validate-attributes	Validate attributes
GET	/location-policies	Meta: list policies
GET	/location-categories	Meta: list categories
GET	/location-types	Meta: list types
GET	/location-types/:key	Meta: type detail
GET	/location-types/:key/attributes	Meta: type attributes

9.2 Error Codes Reference

Code	Description
location.not-found	Location not found
location.parent-not-found	Parent location not found
location.type-not-found	Location type not found
location.type-hierarchy-invalid	Type hierarchy invalid
location.circular-reference-self	Cannot set as own parent
location.circular-reference-descendant	Cannot set parent to descendant
location.has-active-children	Has active children (block deactivate/delete)
location.has-children	Has children (block hard delete)
location.code-duplicate	Code already exists in org unit
location.invalid-policy-keys	Policy keys not valid

9.3 Glossary

Term	Definition
Location	Entity fisik/logis (gudang, kantor, rak, dll.) dalam struktur hierarkis
Organization Unit	Branch/cabang yang memiliki lokasi
Category	Klasifikasi lokasi (warehouse, office, retail, dll.)
Type	Tipe spesifik lokasi dalam category (rack, shelf, building, dll.)
Policy	Kemampuan operasional (inventory.view, transfer.inbound, dll.)
Soft Delete	Set is_active = false; data tetap ada
Hard Delete	Hapus permanent dari database
LTree	PostgreSQL extension untuk path hierarkis
Path	String path (e.g. 0001.0002.0003) merepresentasikan posisi dalam tree

9.4 Document References

• TEKNIS.md — Technical Documentation (arsitektur, implementasi)
• Validation-rule.md — VALIDATION-RULES