Refactor Human Resources and Payroll Management

[jniles]

This PR is ready for testing and merge, once #7979 lands.

It's main contribution is a much better logical flow to the payroll code on the server, and address some of the UI complaints multiple_payroll module. Because little was changed in the data model (SQL) or the core of the UI, the tests were not needed to be extensively updated.

The old PR description is found below to denote the journey we've been on in this PR.

Previous PR Description:

This PR reworks the underlying Human Resources and Payroll Management code and procedures to allow for better code readability, maintainability, efficiency and testing. It is part of an effort to rewrite the payment processes to support multiple payroll systems in a unified way (#7752).

All updates and changes are being made a feature branch refactor-payroll-management. This is the PR pulls that branch into master. It will be marked as a draft, and should not be merged until it is marked as needing review.

General Approach

The general approach for this refactor is to:

1. Improve code quality by using modern JS techniques (async/await, Promise, etc) and removing unused code paths.
2. Add comments and debug() calls to complex tasks to document code behavior.
3. Encapsulate common code within bespoke functions to make the code self-documenting (e.g. isBenefitRubric())
4. Server APIs gained the payroll/ prefix where there might be confusion (e.g. account_config/ -> payroll/account_config/)
5. Tackle outstanding payroll issues from the issue tracker.

Some notable changes:

1. The Rubric Configuration interface was unified (Unify Rubric Configuration Modal #7952).
2. The Function UI gained additional descriptive text (Feature: Display number of employees per Function #7955)

Issues Tackled

The following issues are tacked in part or in whole:

• Add descriptive text to "RETENUE DU PAIEMENT" transactions #7791 (descriptive text only applies to the commitmentByEmployee() function so far).
• Payroll cosmetic requests #6097 (better English descriptions for payroll tasks).
• Include the number of employees in each position on the "Function" page. #7797.
• Rename employee "date_embauche" to "hiring_date", for better English consistency #7821.

Payroll Concepts and Definitions (as expressed by BHIMA)

For a review of the DRC Human Resources definitions, see #7969. Below, we discuss how these concepts are expressed in BHIMA.

There are four basic types of payroll modifications: benefits, payroll taxes, withholdings, and pension allowances.

• Benefits are any rubrics that are paid to an employee. In the current implementation of BHIMA payroll, the employee's base salary is classified as a benefit. However, benefits can also be bonuses, additional compensation for family members, etc.
  • A benefits rubric is identified by the flag: is_discount === 0.
• Payroll Taxes are called "charge sur remuneration" in French. These taxes are paid by the enterprise and are not born by the employee.
  • They are identified by the flags is_employee !== 1, is_discount === 1, is_linked_pension_fund === 0.
• Withholdings are monies retained/deducted by the institution from the employee's pay. This might be due to paying back salary advances, taking health insurance, or setting aside in an employee savings account.
  • They are identified by is_discount === 1 and is_employee === 1.
• "Pension Funds" are retirement funds that are deducted from the employee salary.
  • They are identified by is_employee !== 0, is_discount === 1, and is_linked_pension_fund ===1.

Note: we should probably rename "withholdings" to "deductions".

Notable and/or Breaking Changes

1. Renamed the API for /account_config/ to /payroll/account_config/ since it is used to configure accounts used in the payroll modules.
2. Setting DEBUG to include payroll:* spews out much more informative information about the transaction process.
3. The logic for determining different rubric types (e.g. taxes, pension, etc), has been moved to a common.js function and is shared across all commitment types. It also has some rudimentary tests.
4. commitmentByEmployee() now calls out to relevant calculate*() functions for taxes, withholdings, pension and benefits. This should make the code somewhat more legible.

Testing

We don't have very many payroll tests. In particular, I'm not sure we have tests for all the different types of commitment functions listed in the enterprise settings. Which means that, should this get merged, we cannot be 100% this code will not break something in production.

Ideally, I'm hoping to continue to hack on payroll over the holidays until we get something that is easy to reason about, maintain, and trace if a regression or a bug occurs. However, we probably shouldn't do a release and/or upgrade until we have better test coverage or assurance that the payroll code isn't going to break in mysterious ways at one of the production sites.

Future Work

This PR addresses only about a quarter of the needed payroll refactor. In many ways, it addresses the low-hanging fruit of function signatures and variable hoisting. More in depth refactor is needed in the following areas:

1. Add functions to determine taxable/nontaxable income to payroll/multiplePayroll/common.js, document them, and test them.
2. Apply a similar refactor seen here to files and functions in multiplePayrollIndice associated with multiple indexes.
3. Apply a similar refactor to payrollSettings and associated files.
4. Rework the commitFunction#dataCommit() function to have a simpler function signature.
5. Document the different payroll flows in the code.

On thing I noticed while working on this refactor: there are several places where we loop through employees and compute rubric values that are nearly identical. For example, each commitment function (commitment.js, groupedCommitment.js, commitmentByEmployee.js) loops through the employees, but generates slightly different transactions with the results. With the current code structure, this is fine. However, there is likely a way to make some sort of intermediate representation of the data that is common between all three that we can then reuse for all three.

As an example, one can imagine some sort of pseudocode like this:

const employeeRubricAssignments = loopThroughEmployeesAndComputeRubrics(employees, rubrics) 

// if groupedCommitment.js
const transaction = createGroupedVouchers(employeeRubricAssignments);

// if commitment.js
const transaction =createCommitmentVouchers(employeeRubricAssignments);

// if commitmentByEmployee.js
const transaction = createIndividualVouchers(employeeRubricAssignments);

An advantage of this style is that we could then write unit tests for the loopThroughEmployeesAndComputeRubrics() function and ensure that we are correctly expressing the rubrics as transactions. It would make it faster and easier to write a variety of tests for different scenarios (e.g. multiple pension withholdings, increases of greater than 100%, etc).

Payroll Order of Operations

I spoke to Nancy Allan, who guided me through the basic payroll order of operations. They are:

1. Take the employee base salary.
2. Compute the taxes due to CNSS (usually ~5%)
3. Compute the taxes due to IPR (usually ~30%).
4. Then you can add on housing and transport, which are typically untaxed.
5. This provides the net salary that you will pay to the employee.
6. Finally, the company/employer's taxes are calculated on the net salary. This is usually ~13% of the gross salary.

It should be noted that pension and taxes on pension are separate calculations.

Unanswered Questions:

1. How are payroll taxes that are born by employees, versus those born by the institution, modeled?
2. Why is there a different classification of rubrics in the "payroll by indice" modules?
3. How do we model overtime (heurs supplimentaire) using rubrics? Are they automatically calculated?