RFC 004: HR & People Operations Specification

1. Domain Database Models

The HR & People Operations Suite defines core staffing and nominee records mapped to PostgreSQL using class-based definitions:

class Employee(BaseDocType):
    """Core employee personal and professional profile."""

    personal_number: str = Field(max_length=20, unique=True)
    first_name: str = Field(max_length=100)
    last_name: str = Field(max_length=100)
    date_of_birth: date
    joining_date: date
    status: str = Field(default="Active", description="Active, Retired, Resigned, Suspended")
    designation: str = Field(description="Designation ID reference")
    pay_scale: str = Field(description="PayScale ID reference")
    current_basic: Decimal = Field(default=Decimal("0.00"))

    class Meta:
        table_name = "employee"
        indexes = ["personal_number", "status", "designation"]

class EmployeeFamily(BaseDocType):
    """Employee family nominee directory for medical benefits and pension plans."""

    employee_id: str = Field(description="Link to parent Employee")
    full_name: str = Field(max_length=200)
    relationship: str = Field(description="Spouse, Son, Daughter, Father, Mother")
    date_of_birth: date
    is_medical_dependent: bool = Field(default=True)
    is_pension_nominee: bool = Field(default=False)

    class Meta:
        table_name = "employee_family"
        indexes = ["employee_id"]

---

2. Leave Allocation State Machine

Employee leave balances (LeaveLedger) are managed using a strict, auditable transaction ledger:

stateDiagram-v2
    [*] --> Unallocated
    Unallocated --> Allocated : Auto-Credit Job
    Allocated --> Reserved : Leave Application Submitted
    Reserved --> Debited : Leave Order Approved
    Reserved --> Allocated : Leave Restored

• Transactional Ledger: Leaves are never updated via direct addition/subtraction on an integer column. The system writes LeaveLedgerEntry rows tracking credited_qty and debited_qty.
• Balance Assertion: The current available balance is computed dynamically using: $$\text{AvailableBalance} = \sum \text{credited_qty} - \sum \text{debited_qty}$$

---

3. Pension Disbursement & Gratuity Engines

Upon retirement, the pension engine calculates long-service disbursements:

3.1 Gratuity Computation

$$\text{GratuityPayout} = \frac{\text{YearsOfService} \times \text{FinalBasicPay}}{2}$$ (Capped at corporate policy thresholds, e.g., maximum INR 2,000,000)

3.2 Commuted Pension & Monthly Disbursement

• Retiring employees can commute up to 40% of their standard pension.
• Monthly Nominal pension: Computes the monthly payment nominal file: $$\text{MonthlyPension} = (\text{FinalBasicPay} \times 50%) - \text{CommutedPortion}$$
• The system posts these transactions as monthly Liabilities through the m-ledger core to post bank disbursements directly to the General Ledger.