O3-5174: Prevent duplicate billable services in bills

[RajPrakash681]

Fix: Prevent duplicate bill line items

Problem

When adding the same service/item to a bill multiple times, the system was creating duplicate line items instead of incrementing the quantity on the existing line item.

Solution

Added a Liquibase migration that:

1. Cleans existing duplicates - Merges duplicate line items by summing their quantities
2. Prevents future duplicates - Creates a unique index on (bill_id, service_id, item_id, price_id, price, voided)
3. Handles NULL values - Uses COALESCE to properly handle NULL service_id, item_id, and price_id
4. Idempotent execution - Uses MARK_RAN precondition to safely run multiple times

Testing Performed

• Module builds successfully: mvn clean install
• No compilation errors
• Liquibase XML syntax validated
• OMOD file generated: billing-1.3.3-SNAPSHOT.omod
• Changeset structure verified with proper preconditions

Database Changes

• New Index: unique_bill_line_item_idx
• Columns: bill_id, service_id, item_id, price_id, price, voided

Migration Behavior

1. Identifies all duplicate line items in cashier_bill_line_item
2. Keeps the first occurrence of each duplicate set
3. Updates its quantity to the sum of all duplicate quantities
4. Soft-deletes other duplicates (sets voided=1)
5. Creates unique index to prevent future duplicates

[RajPrakash681]

@denniskigen
sir I've completed the fix for issue O3-5174 (duplicate billable services) in the backend module as you suggested.

What I did:

Earlier, I had made changes in the billing app (frontend), but following your guidance, I've now implemented the fix in the correct location - the openmrs-module-billing backend module.

[dkayiwa]

Is it possible to have a unique constraint for this at the database level?

[RajPrakash681]

Thanks for the suggestion about adding a database-level unique constraint that’s a good idea! I looked into it, but decided to keep the merge logic at the application layer for a few reasons:

User Experience: When users accidentally add the same service twice, the app automatically merges them instead of throwing a database error. It’s smoother and less frustrating.

Complex Fields: Some fields like item_price_id can be NULL, and handling that consistently across databases is tricky.

Different Item Types: A line item can be either a service or a stock item, which makes a single unique constraint hard to manage.

Precision & Flexibility: Decimal precision and custom merge rules (like keeping the latest price) are easier to handle in code.

Migration Effort: Adding a DB constraint would require cleaning up existing data and writing migration scripts.

[RajPrakash681]

@denniskigen should i close that pr in which i made these changes in billing app?
also review this please!

[RajPrakash681]

@dkayiwa i have tried implementing please have a look !

[dkayiwa]

Can you share an example or a screenshot of the duplicate line items that were created?

[RajPrakash681]

I tested the migration using MySQL commands.

What I verified:

• The Liquibase changeset executed successfully
• The unique index

  unique_bill_line_item_idx

  was created on the

  cashier_bill_line_item

  table
• Index covers all 6 columns:

  bill_id, service_id, item_id, price_id, price, voided

• Non_unique = 0
  ``` confirms it’s enforcing uniqueness  

• Visible = YES
  ``` means the constraint is active  
  

The migration handles existing duplicates by merging them (summing quantities) and soft-deleting duplicate rows before creating the unique constraint.
This ensures duplicate bill line items can’t be created going forward.

[RajPrakash681]

@dkayiwa sir can you have a look here 😊

[RajPrakash681]

@dkayiwa sir any update on this pr?

[denniskigen]

Any ideas about how to move this forward, @ibacher, @wikumChamith, @dkayiwa?

[wikumChamith]

Any ideas about how to move this forward, @ibacher, @wikumChamith, @dkayiwa?

As we are planning on a major release I think we could just add the unique constraint at the database level. This will cause issues if someone has duplicate entries if they try to update. However rather than we are deciding what to do I think it would be better to get handled by the maintainers of those implementations. This is what happens when a system is not well thought out at the start :)

[ibacher]

So:

1. I'm still not convinced this is something we want to move forward with. I raised some issues in the ticket, which is the right place to discuss this. I don't think this is well-specified enough yet for a PR.
2. We do not generally use database-level uniqueness constraints for anything other than UUIDs, so I'm kind of confused why we're trying to do so here.

[RajPrakash681]

@denniskigen @ibacher @dkayiwa any idea or comments now, how to proceed with this?