# Department Management

## Overview

Departments represent functional organizational units within a company — such as Sales, Engineering, Finance, and Human Resources. Each department belongs to exactly one company and is identified by a unique code scoped to that company. Departments form a self-referential hierarchy through an optional parent department reference, enabling the modeling of organizational trees (e.g., Engineering > Backend Engineering > Platform Team). Each department carries a lifecycle state of ACTIVE or INACTIVE and a human-readable name. Departments serve as the primary structural unit for grouping business functions and are referenced by downstream modules. Manager assignment is owned by a future HR/employee module where the manager is an employee/worker reference, not a login identity.

## Business Purpose

Departments provide the foundational organizational structure that other modules build upon. This enables:

- Modeling the functional structure of a company as a hierarchical tree
- Scoping operational data (budgets, headcount, approvals) to specific organizational units
- Deactivating departments that are no longer in use without losing historical references
- Enforcing unique department codes per company for reliable cross-system integration

## Process Flow

```mermaid
flowchart TD
    A[Create Department] --> B{Has parent?}
    B -->|Yes| C[Set parent department]
    B -->|No| D[Top-level department]
    C --> E[Department ACTIVE]
    D --> E
    E --> F{Restructure needed?}
    F -->|Reassign parent| G[Update parent reference]
    G --> E
    F -->|No longer needed| H{Has active sub-departments?}
    H -->|Yes| I[Block deactivation]
    I --> F
    H -->|No| J[Deactivate Department]
    J --> K[Department INACTIVE]
    K --> L{Reactivate?}
    L -->|Yes| E
    L -->|No| M[Remains INACTIVE]
```

## Scenario Patterns

- **Initial Org Structure Setup**: A company is created and its top-level departments (Sales, Engineering, Finance, HR) are added as ACTIVE departments with no parent. Sub-departments are then created beneath them to reflect the real organizational hierarchy.
- **Department Restructuring**: A reorganization moves the "DevOps" department from under "Engineering" to under "Infrastructure" by updating its parent department reference. All sub-departments of DevOps move with it implicitly through the hierarchy.
- **Department Deactivation**: The "Legacy Products" department is no longer needed. After confirming it has no active sub-departments, it is set to INACTIVE. Historical records that reference this department remain intact.
- **Department Reactivation**: A previously deactivated "Partnerships" department is reactivated when the company re-enters a market segment, restoring it to ACTIVE status for new assignments.
- **Cross-Company Isolation**: Two companies in the same tenant each have a department with code "ENG". The codes are unique per company but do not conflict across companies.

## Test Cases

- A department is created in ACTIVE status by default
- Department code is required, unique per company, and immutable after creation
- Department name is required and must be non-empty
- A department must reference an existing, valid company
- Setting a parent department creates a hierarchical relationship
- A department cannot reference itself as its own parent
- A department cannot be deactivated while it has active sub-departments
- Deactivating a department sets its state to INACTIVE
- Reactivating an INACTIVE department sets its state to ACTIVE
- Updating a department's parent department is allowed on both ACTIVE and INACTIVE departments
- Department codes from different companies do not conflict (company-scoped uniqueness)
- Circular parent references are rejected (A -> B -> C -> A)
- Deleting a company is restricted (rejected) if it has existing department references

## Reference Links

- [SAP Organizational Units](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/5765fa03d4c34ae7b8965e7a41d7c077/af204256a1f84457b2c3f16825e6af89.html)
- [Odoo Departments (HR)](https://www.odoo.com/documentation/19.0/applications/hr/employees/departments.html)
- [Dynamics 365 Operating Units](https://learn.microsoft.com/en-us/dynamics365/fin-ops-core/fin-ops/organization-administration/organizations-organizational-hierarchies)