Pharmacy Module Development Guide

Key Documentation

For detailed pharmacy development, refer to these files:

• Pharmaceutical Management API - REST API for managing VTM, ATM, VMP, AMP, VMPP, AMPP, categories, dosage forms, and measurement units
• GRN Fixes - GRN completion patterns
• Multi-Window Sales - Multi-window handling
• Cost Accounting Signs - Sign normalization
• Disbursement Signs - Disbursement conventions
• Quantity Decimals - Decimal validation
• Transfer Disbursement - Transfer workflow
• Purchase Order Workflow - PO workflow
• Pharmacy Token Workflow - Token issue → Retail Sale / Sale for Cashier → pay → call → complete; which bean backs each sale page
• Bulk Stock Verification Adjustment - Reconciling a physical stock count spreadsheet against system stock at scale via the adjustment/batch-creation APIs

Configuration Options

Pharmacy uses configOptionApplicationController.getBooleanValueByKey() for feature toggles. Key patterns:

• Pharmacy Transfer is by Purchase Rate / Cost Rate / Retail Rate
• Display Colours for Stock Autocomplete Items
• Pharmacy Disbursement Reports - Display * (various column visibility)
• Pharmacy - Allow Cross-Department PO Receiving (default false) - lets a PO created in one department be received/GRN'd from any other department in the same institution; see Purchase Order Workflow § Receiving Department Scoping

Common Patterns

Stock Queries

• Always include s.retired = false and s.itemBatch.item.retired = false
• Filter inactive items with s.itemBatch.item.inactive = false
• Use DTOs for display, entities for business logic

Transfer Workflow

• Transfer Request -> Transfer Issue -> Transfer Receive
• Each step creates a Bill with appropriate BillType
• Sign conventions matter for cost accounting

Retail Sale

• Use StockDTO for autocomplete performance
• Cache autocomplete results for converter
• Defer expensive discount calculations

Store module

• Hospitals issue and return Store items to BHTs through the pharmacy flow and controllers (e.g. BhtIssueReturnController). The bean/store/*ReturnController pages are still reachable (Theatre / Store → BHT Issue menus) but aren't used in practice. Don't add fixes or guards there unless an issue explicitly reports that path; fix the pharmacy controller and say so in the issue.

GRN Report Testing

When testing GRN / Direct Purchase report changes:

• The ruhunu local database typically has richer GRN data than rh and is better for testing
• Test URL: http://localhost:8080/rh/faces/reports/inventoryReports/grn.xhtml
• Print view (navigated from grn.xhtml): grn_detailed_view.xhtml, grn_summary_view.xhtml
• Key bill types: PHARMACY_GRN, PHARMACY_GRN_RETURN, PHARMACY_GRN_CANCELLED, PHARMACY_DIRECT_PURCHASE, PHARMACY_DIRECT_PURCHASE_REFUND, PHARMACY_DIRECT_PURCHASE_CANCELLED
• PHARMACY_DIRECT_PURCHASE bills have null referenceBill — always null-guard before accessing bill.getReferenceBill()
• Date/time formats in exports must use sessionController.getApplicationPreference().getLongDateTimeFormat() — never hardcode
• Excel/PDF filenames must not contain colons — use getLongDateFormat() (not datetime) and sanitize with .replaceAll("[: /]", "_")

Backward Compatibility

• Never "fix" purcahseRate spelling - it's a database column name
• Never rename composite components without checking ALL usage