Direct Goods Receipt

Direct Goods Receipt records stock that enters the selected branch without starting from a branch-transfer document. The user creates the receipt from product inventory context, assigns quantity and batch data, then submits a stock-in payload to the API/MST layer.

App Entry Points

App	Target
Mobile	GoodsReceiptList -> GoodsReceiptDetail
POS Terminal	goodsReceipt -> GoodsReceiptDetailForm

End-To-End Workflow

Key Business Rules

Rule	Behavior
Batch source	The user must enter a Container No. or vehicle plate before adding products. The app uses the last four digits as the batch suffix.
Batch prefix	The prefix comes from generateBatchCode(getSelectedWhsGrpCode(branch), receiptDate) so the selected branch and receipt date affect the final batch number.
Product source	Products come from branch inventory context plus dummy products; filtering keeps company-compatible products.
Product add quantity	The selected product quantity must be greater than 0.
Receipt line quantity	Submit blocks blank quantities and negative quantities. 0 can be submitted only through the explicit zero-batch behavior below.
Batch required	Submit blocks lines with no batch rows, blank batch numbers, blank batch quantities, negative batch quantities, or duplicate batch numbers.
Zero-batch branch	A line that has batch rows but cal === 0 asks for confirmation; after confirmation the payload sends the original line quantity and no useful batch quantity for that line.
Deposit warehouse	Non-main branch/deposit context uses deposit due-date fields. Mobile validates expiry/due dates before submit; Terminal currently carries deposit dates in payload and enforces the quantity/batch guards in this form.
Extra batch quantity	For normal items, if batch total is greater than line quantity, the payload splits the excess into an extra line with lineNum: -1. For BT- items, the submitted line uses the batch total directly.

Payload Shape

The submit handler sends branch and user identity with normalized numeric item values.

Important implementation notes:

• admissionDate is the submitted receipt-date key; the obsolete addmisionDate key is not sent.
• dueDate is included only for deposit warehouse flows. Both admissionDate and dueDate are submitted as YYYY-MM-DDTHH:mm:ss.
• Lines with batch rows and cal === 0 are sent without batch data after explicit user confirmation.
• receiptDate defaults to the start of the current day but can be changed before generating/submitting batch dates.

Field Dictionary And Provenance

This covers every field Mobile and POS Terminal read or send in this flow. It excludes future backend-only response properties allowed by the model index signature. The selected document comes from GET /goods-receipt-po?branchId={selectedBranchId}; both apps spread that document into the POST /stock-in payload, then override the fields below.

Header

Field	Meaning	Source / submit rule
company	Document company code	Passed through from goods-receipt-po.
docEntry, docNum	Internal ID and PO number	Passed through from the response.
docDate, docDueDate, taxDate	Document, due, and tax dates	Passed through from the response.
cardCode, cardName, comments	Supplier identity and document comment	Passed through from the response.
numAtCard	Supplier reference number	Passed through from goods-receipt-po; this flow does not generate it.
branchId	Document branch ID	Passed through; selected branch ID scopes the list request.
branchCode, branchName	Receiving warehouse-group code/name	Overridden from selected whsGrpCode/whsGrpName, falling back to the document.
userCode, userName, whsEmpName	Recording user and warehouse employee	Current logged-in user; code falls back to the document.
payloadBefore	Immutable pre-edit JSON snapshot	Created with JSON.stringify(goodsReceipt) in the detail screen.

Lines and batches

Field	Meaning	Source / submit rule
lines[].lineNum	Document line sequence	From API; user-added lines use -1; sorted before submit.
itemCode, itemDescription	Item identity	Existing line API data, or selected inventory/dummy product.
quantity, weight	Received quantity and weight	Converted to numbers; normally batch total (cal), but the original line quantity is retained for no/zero-batch flow.
uomCode, uomEntry	Unit code and ID	Existing line or selected product salUom*.
warehouseCode	Receiving warehouse	Existing line; new line uses product warehouse, then branch code, then warehouse group.
costingCode–costingCode5, poRemarks	Cost centers and PO line note	Existing API line; new cost-center values start blank.
batchNumbers[].batchNumber, quantity	Batch ID and received batch quantity	User-selected/entered; new generated values use warehouse/date plus container/plate suffix.
admissionDate	Receipt date	Selected receiptDate, submitted as YYYY-MM-DDTHH:mm:ss.
manufacturingDate, expiryDate, dueDate	Batch manufacture, expiry, and deposit due dates	Batch editor/existing data; dueDate is sent only for deposit/non-main warehouses and uses YYYY-MM-DDTHH:mm:ss.

Permissions And Guards

Topic	Behavior
Terminal menu key	goodsReceipt
deptCode menu set	-2, 1, 2, 3, 4, 7, 29, 21, 8, 9, 12, 22, 27, 28
Branch rule	allowNonMainBranch = true; on a non-main selected warehouse the menu is accessible even when the user's deptCode is not in the stock menu set.
Full non-main access	Users with non-main warehouse full access can pass menu access checks across these stock menus.
Required local state	Selected branch and user are loaded from local storage before submit.

Mobile vs POS Terminal

Topic	Mobile	POS Terminal
Navigation	Dedicated stack screens	HomeScreen split-pane detail form
Product add	Full-screen picker/modal flow	Detail panel modal flow
Batch behavior	Quantity, duplicate batch, and date validation	Quantity and duplicate batch guards; deposit dates are carried in payload
UX after save	Return/replace list screen	Refresh list pane and close detail

Developer Handoff Map

Area	Code
Mobile list/detail	apps/mobile/src/screens/goodsReceiptStack/goodsReceiptListScreen, goodsReceiptDetailScreen
Terminal detail	apps/pos-terminal/src/screens/HomeScreen/GoodsReceiptDetailForm.tsx
Mobile service	apps/mobile/src/services/goodsReceipt.ts
Terminal service	apps/pos-terminal/src/services/goodsReceipt.ts / goodsReceipts.ts
Shared rules	@bsr/utils batch helpers, utils date/quantity validators

Related Docs

• Transfer In From Branch
• Freezer / Warehouse Transfer