Analysis request - Added or removed services after initial save should update relevant transactions

[ibrahimhuycn]

Current Scenario

If an analysis request is saved, transactions, transaction and payer allocations also get saved for the same episode. Any additional services added or saved after initial save does not have their transaction records and payer allocations inserted or removed or marked as removed.

Required behavior

Subsequent addition or removal of services to the episode should add or remove the relevant transaction records provided that they are not paid for... i.e., they are no payment records for the transaction line item.

What happens if there are payment records?

• If paid, service cannot be removed until refunded and.... refund is approved?
• What happens if payment is complete, and a new service is to be requested for the same episode? Can we have a voucher(memo) and the payment records be memo details? In that case, can we have multiple memos for the same episode. Any alternative names for voucher/memo for this?
• HMS Link will not allow sample collection if unpaid services exist?

[ibrahimhuycn]

🏥 Feature Request: Update Transactions When Services are Added or Removed

Current Behavior

When an analysis request is saved, the system creates transactions and payer allocations for the episode. However, if additional services are added or removed after the initial save, the system does not:

• Insert transactions for newly added services.
• Remove or mark transactions as voided for removed services.
• Adjust payer allocations accordingly.

Required Behavior

Subsequent addition or removal of services to an episode should automatically update transactions, provided that no payment has been made for the transaction line item.

Behavior When Payment Records Exist

• If a service has been paid, it cannot be removed until a refund is approved.
• If payment is complete, and a new service is added to the episode:
  • The system should create a voucher (memo), and the payment records should be memo details.
  • Multiple memos should be allowed per episode.
  • Alternative names for the memo: Adjustment Invoice, Debit Memo, Supplementary Invoice.
• Sample collection should be restricted if unpaid services exist, unless an override is granted.

---

🛠️ State Machine for Service Transactions

📌 States

1. Pending – Service added but not yet finalized (before initial save).
2. Active – Service saved, transaction and payer allocation created.
3. Paid – Payment received for the service.
4. Cancelled – Service removed before payment.
5. Refund Pending – Service has payment, but refund approval is in process.
6. Refunded – Refund approved and processed, transaction marked as void.
7. Adjustment Required – New service added post-payment, requiring an adjustment invoice or memo.

📊 State Transition Diagram

(New Service)
│
▼
[ PENDING ]
│ │
│ ├────────► [ CANCELLED ] (If removed before save)
▼
[ ACTIVE ]
│ │
│ ├────────► [ CANCELLED ] (If removed before payment)
▼
[ PAID ]
│ │
│ ├────────► [ REFUND PENDING ] ───► [ REFUNDED ]
│ │
│ ├────────► [ ADJUSTMENT REQUIRED ] (If a new service is added post-payment)
▼
[ SAMPLE COLLECTION ALLOWED ] (If all services are paid)

🔄 State Transitions and Triggers

Current State	Trigger	Next State	Notes
Pending	Service saved	Active	Transaction & payer allocation created
Pending	Service removed	Cancelled	No transaction created
Active	Payment received	Paid	Transaction finalized
Active	Service removed (Unpaid)	Cancelled	Transaction voided
Paid	Refund requested	Refund Pending	Approval process starts
Refund Pending	Refund approved	Refunded	Transaction voided
Paid	New service added	Adjustment Required	Requires adjustment invoice
Adjustment Required	Adjustment invoice created	Paid	New transactions recorded

---

💡 Edge Cases to Consider

• Partial payments: If an episode has multiple services, some paid and some unpaid, should unpaid services be removable?
• Insurance payer behavior: If an insurance provider is involved, should a pre-authorization be required before adjustments?
• Emergency override for sample collection: Should an admin role be able to allow sample collection despite unpaid services?

---

✅ Acceptance Criteria

• Adding a new service after initial save inserts the relevant transaction and payer allocation.
• Removing an unpaid service deletes the transaction and payer allocation.
• Removing a paid service requires refund approval.
• Adjustments (memos, vouchers) are generated when a new service is added post-payment.
• Sample collection is blocked if unpaid services exist, unless overridden.
• The system maintains audit logs for service additions/removals and payment changes.

---

🚀 Implementation Notes

• Use database transactions to ensure atomic updates.
• Maintain audit logs for state changes.
• Implement role-based approvals for refunds.
• Provide UI alerts if users try to delete a paid service.