# Stock Receipts

Stock Receipts extends Stock Replenishment without replacing its request, review, preparation, or dispatch workflow. The warehouse's official Stock Transfer Receipt PDF is the receiving source document.

## Workflow

1. The owning salesman uploads a text-based warehouse STR PDF.
2. Laravel stores the original privately, hashes it, parses every page, validates the document total, and matches each line by exact SKU/barcode.
3. Flutter shows the complete parsed warehouse list, STR metadata, SKU/barcode/name, document quantity, and match state before receiving begins.
4. A possible Stock Request is suggested only; linking requires an explicit action.
5. The salesman chooses **Accept Document Quantities** or **Count Manually**. Quick Accept is blocked by unresolved lines and copies Document Qty into Counted and Accepted; manual mode retains scanner/SKU counting.
6. Both modes are server-side resumable. Summary lines remain editable before confirmation.
7. Quick Accept and Finish Counting record review state but never change stock.
8. Confirm Receipt posts accepted quantity only, atomically and exactly once, to sellable VAN stock.

Short, excess, damaged, unexpected, unmatched, and ambiguous lines remain visible in the receipt audit. An unmatched or ambiguous document line blocks confirmation until safely resolved. Multiple independent receipts may be linked to one Stock Request.

## Source documents

The parser is covered by unchanged fixtures `STR-12920-ABDALLAH.pdf` (28 SKUs / 143 pieces / two pages) and `STR-12921-ABDALLAH.pdf` (6 SKUs / 74 pieces). OCR is not used because the official PDFs contain extractable text.

## Stock safety

Upload, parse, link, start, count, Quick Accept, finish, summary edits, or reopening a receipt does not alter stock. Confirmation uses a database transaction, row locks, a direct receipt relation on each movement, and a unique per-line movement key. Replaying confirmation creates no additional balance or movement.