# Invoice controls and record migration

Run `php artisan migrate` after pulling.

## Billing
Managers/admins can exclude or restore individual draft charges with a mandatory reason. Excluded lines retain their source identifiers and snapshot amounts, but do not contribute to payable totals or patient invoice prints. Internal review and immutable change events preserve the reason and actor. Excluding a charge does not undo clinical care or stock.

Managers can move whole included lines into a linked draft for the same patient, facility, currency and visit. At least one included line stays on the original. Labels are billing references; no insurer entitlement, percentage allocations, quantity splitting, refunds or payment transfers are implied. Issue and collect each bill separately. Issued invoices and bills with any payment history are locked for these controls.

## CSV imports
Administration > Data imports supports patients, inventory catalogue and billable services. Physicians can import historical entries using existing patient numbers and facility codes. Download the corresponding template. No existing data is overwritten; natural identifiers, duplicate rows and possible duplicate patient identities are checked. All rows must pass validation. Review the preview, then commit explicitly. Commit validates again and uses a single transaction; repeating the same batch commit does not duplicate records.

UTF-8 CSV, 500 records, 2 MB limit. Keep identifiers as text, dates YYYY-MM-DD. Historical entry categories: visit_summary, diagnosis, allergy, medication, procedure, lab_result, clinical_note. Each legacy historical entry needs a stable, unique external_reference. These are historical facts rather than current orders. Physicians must compare histories with their original sources before committing.

Preview content is encrypted, available for 24 hours, and cleared on commit/discard or when expired batches are cleaned on the import listing. Batch summaries and audit metadata remain.

## Scanned and digital patient documents
Patient care > Historical records accepts scanner/phone images, PDF, DOCX and TXT. Choose the exact patient number and facility. Files remain on the private local storage disk; downloads, extracted text and search enforce clinical role, tenant and facility access. Duplicate file hashes for a patient reuse the existing source.

Extraction is a queued job. Run a persistent worker (Supervisor/systemd or hosting-supported process management):
```sh
php artisan queue:work --tries=1 --timeout=80
```
Use the application's database queue and ensure its jobs table is migrated. The database queue retry_after must exceed 80 seconds. A cron-managed worker may use --stop-when-empty when persistent workers are unavailable. Do not expose storage/app/private publicly.

Install local tools:
- Poppler: pdfinfo, pdfimages, pdftotext, pdftoppm.
- Tesseract OCR with the eng language data (additional language packs can be configured).
- PHP ZIP and DOM extensions for DOCX.

On Debian/Ubuntu an administrator can install poppler-utils, tesseract-ocr, tesseract-ocr-eng and the PHP ZIP extension matching the PHP version. For Namecheap/cPanel, ask the host whether these executables, PHP process execution and queue workers are supported. Configure full binary paths through HMS_PDFINFO_BIN, HMS_PDFIMAGES_BIN, HMS_PDFTOTEXT_BIN, HMS_PDFTOPPM_BIN and HMS_TESSERACT_BIN. HMS_OCR_LANGUAGE defaults to eng.

PDFs are checked page by page so mixed text/scanned files retain scanned pages. Maximum 10 pages per PDF, 10 MB upload, 60,000 extracted characters and a 60-second extraction budget. Image OCR is supported for JPEG, PNG and TIFF; DOCX paragraphs and tables are read as text. Handwriting and poor scans may require transcription. Legacy DOC files must be converted to DOCX/PDF first.

No document is sent to an external OCR/AI provider. If tools are unavailable, extraction fails, or a document exceeds the limits, the file remains available for manual transcription and clinical review; no partial extraction is silently published.

Physicians verify identity, dates, doses, units, negation and text against the original. Save separate sections into patient history entries. Extracted text is retained encrypted for comparison; reviewed history is searchable by text, patient and category. Corrections supersede older entries without deleting provenance. Imported historical allergies/medications are displayed as historical records, not activated as current alerts or prescriptions.