pharmacy-dev

name	pharmacy-dev
description	Pharmacy module development guide for the HMIS project. Use when working on pharmacy features including GRN, purchase orders, stock transfers, disbursements, retail sales, pharmacy reports, stock management, item substitution, or pharmacy billing workflows.
user-invocable	true

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
• 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

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