# Pharmacy Pack Transactions and Ward Stock Management

## Introduction

HMIS manages all pharmacy stock movements — compounding, unit-dose dispensing, ward stock replenishment, inter-department transfers, purchase orders, and goods receipt — at the **pack level**. Every transaction carries pack size, quantity, and batch information, ensuring that stock values, expiry tracking, and financial accounting remain accurate whether a single tablet or a full case is moved. All major transaction types include a **finalisation and approval step** before stock is committed, providing an audit-controlled workflow suitable for regulated environments.

## Navigation

| Function | Menu Path |
|---|---|
| Ward Issue (BHT) | Main Menu → Pharmacy → Dispensing → Ward Issue |
| Transfer Request | Main Menu → Pharmacy → Transfers → Transfer Request |
| Transfer Issue | Main Menu → Pharmacy → Transfers → Transfer Issue |
| Transfer Receive | Main Menu → Pharmacy → Transfers → Transfer Receive |
| Purchase Order | Main Menu → Pharmacy → Procurement → Purchase Order |
| Goods Receive Note (GRN) | Main Menu → Pharmacy → Procurement → GRN |
| GRN Return | Main Menu → Pharmacy → Procurement → GRN Return |
| Stock Adjustment | Main Menu → Pharmacy → Stock → Adjustment |
| Physical Stock Take | Main Menu → Pharmacy → Stock → Stock Take |

## Pack-Based Transactions

All stock movements in HMIS operate on packs using the **AMPP / VMPP** (Actual Medicinal Product Pack / Virtual Medicinal Product Pack) model from the formulary hierarchy. Every AMP can have one or more AMPP variants representing different pack sizes (e.g., a 10-tablet strip, a 30-tablet bottle, a 500-tablet bulk pack). The corresponding VMPP captures the generic equivalent pack size under a VMP.

Pack-level tracking means:

- A GRN records the number of packs received (AMPP), the pack size, and the unit cost per pack.
- A ward issue records packs and units issued against the AMPP.
- A transfer records AMPP packs moving between stores/wards, preserving pack-size context.
- Bin card and stock history reports show movements in pack units, with drill-down to individual units.
- Pricing, reorder levels, and stock valuation are maintained at AMPP level, so different pack sizes of the same drug are tracked independently.

This supports unit-dose dispensing: if an AMPP is a 30-tablet pack and only 10 are to be dispensed, the system records the fractional consumption against that batch, decrementing stock by 10 units from within the pack.

## Ward Stock Management

### Stock Replenishment Flow

1. The ward or dispensary creates a **Transfer Request** specifying the items and quantities needed.
2. The supplying pharmacy reviews the request and creates a **Transfer Issue** — selecting items, batches, and pack quantities.
3. The issue undergoes **pharmacist approval** (finalisation step) before stock leaves the issuing store.
4. The receiving ward performs a **Transfer Receive**, confirming actual quantities received.
5. The receive transaction also has a **finalisation step** — the receiving store's stock is only updated after confirmation.

### User Stock (Ward-Level Inventory)

`UserStock` tracks inventory held at ward or user level (e.g., ward medication trolleys, ICU stock). This is separate from the pharmacy store stock and enables:

- Ward-level bin cards showing consumption vs replenishment.
- Per-nurse or per-ward allocation tracking.
- Reconciliation between ward holdings and pharmacy issues.

## Compounding

Compounded preparations use the `VirtualProductIngredient` model. The compound AMP lists its constituent ingredients (each a VTM/VMP with quantity and unit). When a compound is dispensed or issued:

- Each ingredient is decremented from stock by the required quantity.
- The compounded item is recorded as the dispensed product.
- Batch information for each ingredient is captured for full traceability.

## Transfer Workflows

### Transfer Request → Issue → Receive

| Step | Actor | Action | Approval Required |
|---|---|---|---|
| Transfer Request | Ward / Dispensary | Request items from source store | — |
| Transfer Issue | Pharmacy | Select items, batches, packs; finalise | Yes — pharmacist finalises before stock leaves |
| Transfer Receive | Receiving Ward | Confirm quantities received | Yes — receiver confirms before stock enters |

If the received quantity differs from the issued quantity, the discrepancy is flagged for investigation.

### Cancellation

Both transfer issues and receives can be cancelled before finalisation (`TransferIssueCancellationController`, `TransferReceiveCancellationController`). Post-finalisation cancellation requires supervisor approval.

## Purchase Order Workflow

| Step | Action | Approval |
|---|---|---|
| Purchase Order Request | Pharmacy creates PO request for supplier | — |
| Purchase Order Approval | Supervisor reviews and approves PO | Yes |
| GRN (Goods Receive Note) | Goods received; batches, expiry dates, quantities captured | — |
| GRN Costing | Purchase cost per pack is set / verified | — |
| GRN Finalisation | GRN approved; stock added to pharmacy inventory | Yes |

### GRN Return

If received goods are damaged, expired, or incorrect:

1. A **GRN Return** is created against the original GRN.
2. Quantities and cost are specified.
3. **GRN Return Approval** (`GrnReturnApprovalController`) is required before the return is committed — stock decremented and supplier liability adjusted.

## Stock Adjustment Workflow

Stock adjustments (rate corrections, expiry date corrections, quantity corrections) follow a similar approval pattern:

1. The pharmacist creates an **Adjustment** specifying item, batch, adjustment type, and reason.
2. The adjustment is saved in **pending** state.
3. A supervisor reviews and **approves** the adjustment.
4. Only on approval does the adjustment affect stock value and history.

Adjustment categories (`AdjustmentCategory`) classify the reason (e.g., data entry error, price revision, physical damage).

## Physical Stock Take

1. Navigate to **Stock Take** (Main Menu → Pharmacy → Stock → Stock Take).
2. Generate a stock count sheet (pre-stock-take snapshot of expected quantities).
3. Staff physically count and enter actual quantities.
4. The system generates an **adjustment bill** for variances.
5. **Stock Take Approval** (`StockTakeApprovalService`) is required before variances are posted.
6. Post-approval, the stock is reconciled to the physical count.

## Medication Administration Reconciliation

Ward stock managed through the BHT issue workflow supports medication administration reconciliation:

- Items issued to the ward are recorded against the patient's BHT.
- Nurses record administration events linked to the BHT issue line.
- Any unused medication is returned via **BHT Issue Return** (`BhtIssueReturnController`), which reverses stock and billing.
- The difference between issued and returned quantities represents actual medication administered — this is the administration record for the episode.

## Technical Reference

| Item | Detail |
|---|---|
| Ward issue controller | `PharmacyIssueController`, `PharmacySaleBhtController` |
| Transfer controllers | `TransferRequestController`, `TransferIssueController`, `TransferReceiveController` |
| Transfer cancellation | `TransferIssueCancellationController`, `TransferReceiveCancellationController` |
| GRN controller | `GrnController`, `GrnCostingController` |
| GRN return controllers | `GrnReturnApprovalController`, `GrnReturnWithCostingController` |
| PO controllers | `PurchaseOrderController`, `PurchaseOrderRequestController` |
| Stock take services | `StockTakeApprovalService`, `StockTakePersistService`, `StockCountGenerationService` |
| Adjustment controller | `PharmacyAdjustmentController` |
| User stock entity | `UserStock`, `UserStockContainer` |
| Compound ingredient | `VirtualProductIngredient` |
| Related | [Pharmacy Dispensing Workflows](Pharmacy-Dispensing-Workflows.md), [Pharmacy Batch Management](Pharmacy-Batch-Management.md) |