Job Position API - Dokumentasi Teknis

Overview

Dokumentasi teknis untuk developer yang akan maintain atau develop lebih lanjut pada Job Position API module.

Arsitektur

Job Position module menggunakan pola Command & Query:

job-position/
├── commands/
│   ├── create.cmd.ts
│   ├── update.cmd.ts
│   └── soft-delete.cmd.ts
├── queries/
│   ├── get.query.ts
│   └── get-by-id.query.ts
├── dto/
├── helper/
├── validation/
├── job-position.controller.ts
├── job-position.service.ts
├── job-position.module.ts
└── docs/

Tech Stack

• Framework: NestJS
• Database: PostgreSQL dengan Prisma ORM
• Validation: class-validator, class-transformer
• Auth: AuthGuard (JWT), tenant dari current user
• RLS: createTenantClient

Database Schema

Table: job_positions

Column	Type	Keterangan
id	UUID	PK
tenant_id	UUID	NOT NULL
title_id	UUID	NOT NULL, FK → job_titles
code	VARCHAR(50)	NULL (unik per tenant)
is_active	BOOLEAN	DEFAULT true
created_by	UUID	NULL
created_by_name	VARCHAR(100)	NULL
created_at	TIMESTAMPTZ	DEFAULT now()
updated_by	UUID	NULL
updated_by_name	VARCHAR(100)	NULL
updated_at	TIMESTAMPTZ	@updatedAt
deleted_by	UUID	NULL
deleted_by_name	VARCHAR(100)	NULL
deleted_at	TIMESTAMPTZ	NULL

Relasi:

• JobPosition.title_id → JobTitle.id
• OrganizationUnitHasPosition.jobPositionId → JobPosition.id
• OpUnitHasPosition → JobPosition
• Employee → JobPosition

Module Structure

1. Commands

CreateJobPositionCommand

• File: commands/create.cmd.ts
• Alur:
  1. createTenantClient(tenantId)
  2. JobPositionValidation.validateExistence(client, { code: dto.code }) — code harus unik (throw jika sudah ada)
  3. JobTitleValidation.validateNotFound(client, { id: dto.title_id })
  4. Transaction: jobPosition.create({ tenantId, titleId, code, isActive: true })
  5. mapToDetailResponse(result)

UpdateJobPositionCommand

• File: commands/update.cmd.ts
• Alur: validateNotFound → validateExistence(code) — bila code diubah, pastikan unik → update

SoftDeleteJobPositionCommand

• File: commands/soft-delete.cmd.ts

2. Validation

JobPositionValidation

• validateExistence(client, where) — Throw 400 job-position.is_exist jika record ada (dipakai untuk validasi code unik)
• validateNotFound(client, where) — Throw 404 job-position.is_not_found jika record tidak ada

3. Create vs Update

• Create: validateExistence({ code }) = code belum dipakai (jika ada → error)
• Update: validateExistence({ code }) dipanggil — perhatian: bila code tidak dikirim (undefined), behavior tergantung implementasi

Controller Endpoints

• Base route: job-positions
• POST / — create
• GET / — findAll
• GET /:id — findOne
• PATCH /:id — update
• DELETE /:id — softDelete

Error Codes

• job-position.is_not_found — Record tidak ditemukan
• job-position.is_exist — Code sudah dipakai (create) / code bentrok (update)
• job-title.is_not_found — title_id tidak valid