From 822a469a22644dc030beeab8c068a40d2001b0a6 Mon Sep 17 00:00:00 2001 From: Tyler Matteson Date: Wed, 19 Mar 2025 12:57:50 -0400 Subject: [PATCH 1/2] wip: restructure docs --- .../{hooks.md => developer/extending_beam.md} | 131 +++++---- beam/docs/developer/index.md | 3 + .../print_integrations.md} | 42 +-- beam/docs/form.md | 20 -- beam/docs/testing.md | 18 -- beam/docs/{demand.md => user/demand/index.md} | 72 ++--- .../handling_units}/hu_traceability_report.md | 0 .../handling_units/index.md} | 248 +++++++++--------- beam/docs/user/index.md | 10 + beam/docs/user/mobile/index.md | 8 + beam/docs/user/mobile/workflows.md | 8 + .../{listview.md => user/scanning/index.md} | 74 ++++-- beam/docs/{ => user/scanning}/matrix.md | 0 beam/docs/user/scanning/workflows.md | 11 + 14 files changed, 353 insertions(+), 292 deletions(-) rename beam/docs/{hooks.md => developer/extending_beam.md} (73%) create mode 100644 beam/docs/developer/index.md rename beam/docs/{print_server.md => developer/print_integrations.md} (98%) delete mode 100644 beam/docs/form.md delete mode 100644 beam/docs/testing.md rename beam/docs/{demand.md => user/demand/index.md} (72%) rename beam/docs/{ => user/handling_units}/hu_traceability_report.md (100%) rename beam/docs/{handling_unit.md => user/handling_units/index.md} (98%) create mode 100644 beam/docs/user/index.md create mode 100644 beam/docs/user/mobile/index.md create mode 100644 beam/docs/user/mobile/workflows.md rename beam/docs/{listview.md => user/scanning/index.md} (57%) rename beam/docs/{ => user/scanning}/matrix.md (100%) create mode 100644 beam/docs/user/scanning/workflows.md diff --git a/beam/docs/hooks.md b/beam/docs/developer/extending_beam.md similarity index 73% rename from beam/docs/hooks.md rename to beam/docs/developer/extending_beam.md index 4551ce04..55168565 100644 --- a/beam/docs/hooks.md +++ b/beam/docs/developer/extending_beam.md @@ -1,52 +1,81 @@ - - -# Extending Beam With Custom Hooks - -Beam can be extended by adding configurations to your application's `hooks.py`. - -To make scanning available on a custom doctype, add a table field for "Item Barcode" directly in the doctype or via customize form. Then add a key that is a peer with "Item" in the example below. - -To extend scanning functionality within a doctype, add a key that is a peer with "Delivery Note" in the example below. - -```python -# hooks.py - -beam_listview = { - "Item": { - "Delivery Note": [ - {"action": "filter", "doctype": "Delivery Note Item", "field": "item_code"}, - {"action": "filter", "doctype": "Packed Item", "field": "item_code"} - ], - } -} - -beam_frm = { - "Item": { - "Delivery Note": [ - { - "action": "add_or_increment", - "doctype": "Delivery Note Item", - "field": "item_code", - "target": "target.item_code", - }, - { - "action": "add_or_increment", - "doctype": "Delivery Note Item", - "field": "uom", - "target": "target.uom", - }, - ] - } -} -``` -To add a custom JavaScript function, add the following hook to your application's `hooks.py`. An example implementation is available in the source code. - -```python -# hooks.py - -beam_client = { - "show_message": "custom_app.show_message" -} - + + +# Extending BEAM + + +## Custom Hooks + +Beam can be extended by adding configurations to your application's `hooks.py`. + +To make scanning available on a custom doctype, add a table field for "Item Barcode" directly in the doctype or via customize form. Then add a key that is a peer with "Item" in the example below. + +To extend scanning functionality within a doctype, add a key that is a peer with "Delivery Note" in the example below. + +```python +# hooks.py + +beam_listview = { + "Item": { + "Delivery Note": [ + {"action": "filter", "doctype": "Delivery Note Item", "field": "item_code"}, + {"action": "filter", "doctype": "Packed Item", "field": "item_code"} + ], + }, + ... +} + +beam_frm = { + "Item": { + "Delivery Note": [ + { + "action": "add_or_increment", + "doctype": "Delivery Note Item", + "field": "item_code", + "target": "target.item_code", + }, + { + "action": "add_or_increment", + "doctype": "Delivery Note Item", + "field": "uom", + "target": "target.uom", + }, + ] + }, + ... +} +``` + +To add a custom JavaScript function, add the following hook to your application's `hooks.py`. An example implementation is available in the source code. + +```python +# hooks.py + +beam_client = { + "show_message": "custom_app.show_message" +} + +``` + +## Adding Custom Vue Components + +- Why +- What +- How + +```python +beam_mobile = { + "components": { + "Consume": "./custom_app/custom_app/public/js/Consume.vue", + }, + "routes": [ + { + "path": "/consume", + "name": "consume", + "component": "Consume", + "meta": {"requiresAuth": True, "doctype": "Stock Entry", "view": "form"}, + }, + ], +} + ``` \ No newline at end of file diff --git a/beam/docs/developer/index.md b/beam/docs/developer/index.md new file mode 100644 index 00000000..d39cf7e4 --- /dev/null +++ b/beam/docs/developer/index.md @@ -0,0 +1,3 @@ + + diff --git a/beam/docs/print_server.md b/beam/docs/developer/print_integrations.md similarity index 98% rename from beam/docs/print_server.md rename to beam/docs/developer/print_integrations.md index 11934975..360000ff 100644 --- a/beam/docs/print_server.md +++ b/beam/docs/developer/print_integrations.md @@ -1,21 +1,21 @@ - - -# Print Server - -There are several steps to get a print server connected in ERPNext. First, the `pycups` dependency needs to be installed on the system, which in turn depends on the CUPS project's `libcups` library. See the following links for installation instructions: - -- [OpenPrinting CUPS installation and configuration instructions](https://github.com/OpenPrinting/cups/blob/master/INSTALL.md) -- [PyCUPS dependencies, compiling, and installation information](https://github.com/OpenPrinting/pycups) - -Next, the user must create a new Network Printer Settings document and fill in the information. - -![Screen shot of the Network Printer Settings document fields, including Name, Printer Name, Server IP, and Port.](./assets/network_printer_settings.png) - -A convenient Print Handling Unit button on relevant doctypes enables the user to print new Handling Unit labels directly from the ERPNext user interface. - -![Screen shot showing the Print Handling Unit button at the top of a Material Transfer for Manufacture Stock Entry form.](./assets/print_hu_button.png) - -Any configured network printers will display as options in the Select Printer Setting dialog. - -![Screen shot of the Select Printer Setting dialog with two example printer options displaying as options.](./assets/select_printer_dialog.png) + + +# Print Server + +There are several steps to get a print server connected in ERPNext. First, the `pycups` dependency needs to be installed on the system, which in turn depends on the CUPS project's `libcups` library. See the following links for installation instructions: + +- [OpenPrinting CUPS installation and configuration instructions](https://github.com/OpenPrinting/cups/blob/master/INSTALL.md) +- [PyCUPS dependencies, compiling, and installation information](https://github.com/OpenPrinting/pycups) + +Next, the user must create a new Network Printer Settings document and fill in the information. + +![Screen shot of the Network Printer Settings document fields, including Name, Printer Name, Server IP, and Port.](./assets/network_printer_settings.png) + +A convenient Print Handling Unit button on relevant doctypes enables the user to print new Handling Unit labels directly from the ERPNext user interface. + +![Screen shot showing the Print Handling Unit button at the top of a Material Transfer for Manufacture Stock Entry form.](./assets/print_hu_button.png) + +Any configured network printers will display as options in the Select Printer Setting dialog. + +![Screen shot of the Select Printer Setting dialog with two example printer options displaying as options.](./assets/select_printer_dialog.png) diff --git a/beam/docs/form.md b/beam/docs/form.md deleted file mode 100644 index 32b6e4a7..00000000 --- a/beam/docs/form.md +++ /dev/null @@ -1,20 +0,0 @@ - - -# Form - -The result of scanning a barcode in the form depends on several factors: - - - Is the barcode recognized? - - What doctype is it associated with? - -For example, when an Item is scanned while viewing a Delivery Note record, it will add a row for that item if one doesn't exist, or increment the highest-indexed existing row with that Item's item_code in it. - -| Scanned Doctype | Form | Action | Target | -|-----------------|-----------------------|--------|--------| -|Item|Delivery Note|add_or_increment|item_code| - -Beam uses a [decision matrix](./matrix.md) to decide what action to take based on what kind of doctype has been scanned. - -Custom actions and client side functions can be added by using [hooks](./hooks.md). - diff --git a/beam/docs/testing.md b/beam/docs/testing.md deleted file mode 100644 index f9e5c0e1..00000000 --- a/beam/docs/testing.md +++ /dev/null @@ -1,18 +0,0 @@ - - -# Testing - -## Simulating a Scanner - -Open the browser console. This assumes a barcode of `'9968934975826708157'` which must be sent as a string. - -```js -window.scanHandler.scanner.simulate(document, '9968934975826708157') -``` - -![Screen shot of a new Sales Invoice document. The browser console shows the scanner simulation code with the demo site's Handling Unit for Cloudberries. Running the code added a new row in the Items table for the fruit.](./assets/testing.png) - -## About the Test Suite - -Coming soon diff --git a/beam/docs/demand.md b/beam/docs/user/demand/index.md similarity index 72% rename from beam/docs/demand.md rename to beam/docs/user/demand/index.md index 90c5013a..f3cc302e 100644 --- a/beam/docs/demand.md +++ b/beam/docs/user/demand/index.md @@ -1,30 +1,42 @@ - - -# Demand - -This feature computes the what Items are needed and where they are available. - -### Demand Map - -Demand increases based on the following factors: -- When a Sales Order is submitted -- When a Work Order is submitted - -Demand decreases based on the following factors: -- When a Sales Order is either: - - fulfilled (via a Sales Invoice or a Delivery Note) - - cancelled - - closed - - put on hold -- When a Work Order is either: - - completed (via a Stock Entry) - - cancelled - - closed - - stopped - - + + +# Demand + +This feature computes the what Items are needed and where they are available. + +- Understanding Demand + - Sales demand tracking + - Manufacturing demand + - Soft allocation +- Working with Demand + - Streamline Receiving + - Manufacturing allocation + - Sales fulfillment +- Reports and Analysis + - Demand tracking + + +### Demand Map + +Demand increases based on the following factors: +- When a Sales Order is submitted +- When a Work Order is submitted + +Demand decreases based on the following factors: +- When a Sales Order is either: + - fulfilled (via a Sales Invoice or a Delivery Note) + - cancelled + - closed + - put on hold +- When a Work Order is either: + - completed (via a Stock Entry) + - cancelled + - closed + - stopped + + diff --git a/beam/docs/hu_traceability_report.md b/beam/docs/user/handling_units/hu_traceability_report.md similarity index 100% rename from beam/docs/hu_traceability_report.md rename to beam/docs/user/handling_units/hu_traceability_report.md diff --git a/beam/docs/handling_unit.md b/beam/docs/user/handling_units/index.md similarity index 98% rename from beam/docs/handling_unit.md rename to beam/docs/user/handling_units/index.md index e59e772b..f512d0b9 100644 --- a/beam/docs/handling_unit.md +++ b/beam/docs/user/handling_units/index.md @@ -1,124 +1,124 @@ - - -# Handling Unit - -A Handling Unit is an abstraction for tracking quantities of items that are moved or stored together. It does not replace Batch or Serial numbers, the manufacture of an Item, or the functionality of the Product Bundle, but can supplement these as a way of conveniently grabbing information that would otherwise require a lot of keystrokes to enter. - -By assigning a unique ID to the Handling Unit, it is possible to capture via scanner the item, net quantity, unit of measure and timestamp of the previous transaction, and then act upon that information in context, according to the [decision matrix](./matrix.md). Beam adds a new doctype, Handling Unit, to implement this functionality in ERPNext. - -![Screen shot of the Handling Unit doctype listview. The list shows several new Handling Units that were created for items received via a Purchase Receipt.](./assets/handling_unit_list.png) - -## Listviews -Generally scanning a Handling Unit in a list view will filter to show all the transactions of the doctype with the appropriate Handling Unit. - -## Purchase Receipt -For Purchase Receipts, Handling Units are generated and cannot be supplied by the user. - -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | 40 Ea | - - -## Purchase Invoice -For Purchase Invoices with "Update Stock" checked, Handling Units are generated and cannot be supplied by the user. - -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | 40 Ea | - -When "Update Stock" is _not_ checked, they can be scanned to facilitate data entry but there's no effect in the Stock Ledger. - -## Delivery Note -For Delivery Note, Handling Units are consumed. In the case where less than the total quantity associated with the Handling Unit is being delivered, the existing Handling Unit will refer to the remaining (net) quantity. - -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | 20 Ea | - -Stock Ledger or subsequent transaction -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | 20 Ea | - - -## Sales Invoice -For a Sales Invoice where "Update Stock" is checked, Handling Units are consumed. In the case where less than the total quantity associated with the Handling Unit is being delivered, the existing Handling Unit will refer to the remaining (net) quantity. - -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | 15 Ea | - -Stock Ledger or subsequent transaction -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | 5 Ea | - -When "Update Stock" is _not_ checked, they can be scanned to facilitate data entry but there's no effect in the Stock Ledger. - -The following screen shot shows the stock ledger for the Cloudberry item. The first row shows the receipt of 60 pounds of the fruit via a Purchase Receipt, and the second row is after the sale of 25 pounds via a Sales Invoice that had 'update stock'. Note that both transactions reference the same Handling Unit. - -![Screen shot of the stock ledger tracking the receipt and a sales of the Cloudberry item.](./assets/stock_ledger_after_sale.png) - -## Stock Entry - -### Send to Contractor, Material Transfer for Manufacture and Material Transfer -When material is transferred from one warehouse to another, it will generate a new Handling Unit, even if the entire Handling Unit is being transferred. In a case where less than the total quantity associated with a Handling Unit is moved from one warehouse to another, a new Handling Unit is generated for the new units. Subsequent scans or lookups of the original Handling Unit (123) will return the remainder or net quantity. - -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ----------------------- | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | -40 Ea | -| Cocoplum | Subcontractor Warehouse | 456 | 40 Ea | - -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | -20 Ea | -| Cocoplum | Work In Progress | 456 | 20 Ea | - - -When cancelling a Stock Entry, the user will be given an option to re-combine or let handling units remain tracked separately. - -![Screen shot of the recombine dialog](./assets/recombine.png) - -### Repack and Manufacture - -In the case of a Repack, Material Issue or Material Consumption for Manufacture, a new Handling Unit is generated for the new quantities. - -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | -40 Ea | -| Cocoplum | Storeroom | 789 | 1 Box of 40 | - - -In a case where less than the total quantity associated with a Handling Unit is consumed, subsequent scans or lookups of the original Handling Unit (123) will return the remainder or net quantity. - -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | -20 Ea | -| Cocoplum Puree | Work In Progress | 012 | 1 liter | -| Cocoplum | Scrap | | 1 Ea | - -#### BOM Scrap Item -In a Manufacturing or Repack Stock Entry, scrap items can be toggled to create a Handling Unit corresponding with their scrap quantity. This can be changed after a BOM is submitted. - -![Screen shot of BOM scrap items showing configuration](./assets/bom_scrap_item.png) - -### Material Issue, Material Consumption for Manufacture - -In both these cases, there is no offsetting movement or creation of items. - -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | -20 Ea | - - -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Work In Progress | 123 | -20 Ea | - -### Material Receipt -In the case of Material Receipt, a new Handling Unit is generated for each item. - -| Item | Warehouse | Handling Unit | Quantity | -| ---------------- | ------------------ | -------------- | --------------:| -| Cocoplum | Storeroom | 123 | 20 Ea | + + +# Handling Unit + +A Handling Unit is an abstraction for tracking quantities of items that are moved or stored together. It does not replace Batch or Serial numbers, the manufacture of an Item, or the functionality of the Product Bundle, but can supplement these as a way of conveniently grabbing information that would otherwise require a lot of keystrokes to enter. + +By assigning a unique ID to the Handling Unit, it is possible to capture via scanner the item, net quantity, unit of measure and timestamp of the previous transaction, and then act upon that information in context, according to the [decision matrix](./matrix.md). Beam adds a new doctype, Handling Unit, to implement this functionality in ERPNext. + +![Screen shot of the Handling Unit doctype listview. The list shows several new Handling Units that were created for items received via a Purchase Receipt.](./assets/handling_unit_list.png) + +## Listviews +Generally scanning a Handling Unit in a list view will filter to show all the transactions of the doctype with the appropriate Handling Unit. + +## Purchase Receipt +For Purchase Receipts, Handling Units are generated and cannot be supplied by the user. + +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | 40 Ea | + + +## Purchase Invoice +For Purchase Invoices with "Update Stock" checked, Handling Units are generated and cannot be supplied by the user. + +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | 40 Ea | + +When "Update Stock" is _not_ checked, they can be scanned to facilitate data entry but there's no effect in the Stock Ledger. + +## Delivery Note +For Delivery Note, Handling Units are consumed. In the case where less than the total quantity associated with the Handling Unit is being delivered, the existing Handling Unit will refer to the remaining (net) quantity. + +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | 20 Ea | + +Stock Ledger or subsequent transaction +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | 20 Ea | + + +## Sales Invoice +For a Sales Invoice where "Update Stock" is checked, Handling Units are consumed. In the case where less than the total quantity associated with the Handling Unit is being delivered, the existing Handling Unit will refer to the remaining (net) quantity. + +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | 15 Ea | + +Stock Ledger or subsequent transaction +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | 5 Ea | + +When "Update Stock" is _not_ checked, they can be scanned to facilitate data entry but there's no effect in the Stock Ledger. + +The following screen shot shows the stock ledger for the Cloudberry item. The first row shows the receipt of 60 pounds of the fruit via a Purchase Receipt, and the second row is after the sale of 25 pounds via a Sales Invoice that had 'update stock'. Note that both transactions reference the same Handling Unit. + +![Screen shot of the stock ledger tracking the receipt and a sales of the Cloudberry item.](./assets/stock_ledger_after_sale.png) + +## Stock Entry + +### Send to Contractor, Material Transfer for Manufacture and Material Transfer +When material is transferred from one warehouse to another, it will generate a new Handling Unit, even if the entire Handling Unit is being transferred. In a case where less than the total quantity associated with a Handling Unit is moved from one warehouse to another, a new Handling Unit is generated for the new units. Subsequent scans or lookups of the original Handling Unit (123) will return the remainder or net quantity. + +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ----------------------- | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | -40 Ea | +| Cocoplum | Subcontractor Warehouse | 456 | 40 Ea | + +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | -20 Ea | +| Cocoplum | Work In Progress | 456 | 20 Ea | + + +When cancelling a Stock Entry, the user will be given an option to re-combine or let handling units remain tracked separately. + +![Screen shot of the recombine dialog](./assets/recombine.png) + +### Repack and Manufacture + +In the case of a Repack, Material Issue or Material Consumption for Manufacture, a new Handling Unit is generated for the new quantities. + +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | -40 Ea | +| Cocoplum | Storeroom | 789 | 1 Box of 40 | + + +In a case where less than the total quantity associated with a Handling Unit is consumed, subsequent scans or lookups of the original Handling Unit (123) will return the remainder or net quantity. + +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | -20 Ea | +| Cocoplum Puree | Work In Progress | 012 | 1 liter | +| Cocoplum | Scrap | | 1 Ea | + +#### BOM Scrap Item +In a Manufacturing or Repack Stock Entry, scrap items can be toggled to create a Handling Unit corresponding with their scrap quantity. This can be changed after a BOM is submitted. + +![Screen shot of BOM scrap items showing configuration](./assets/bom_scrap_item.png) + +### Material Issue, Material Consumption for Manufacture + +In both these cases, there is no offsetting movement or creation of items. + +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | -20 Ea | + + +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Work In Progress | 123 | -20 Ea | + +### Material Receipt +In the case of Material Receipt, a new Handling Unit is generated for each item. + +| Item | Warehouse | Handling Unit | Quantity | +| ---------------- | ------------------ | -------------- | --------------:| +| Cocoplum | Storeroom | 123 | 20 Ea | diff --git a/beam/docs/user/index.md b/beam/docs/user/index.md new file mode 100644 index 00000000..7a89e112 --- /dev/null +++ b/beam/docs/user/index.md @@ -0,0 +1,10 @@ + + +# BEAM + +- Basic scanning concepts -what problem(s) does scanning solve +- How is it different than the built in utilities of Frappe + - no camera, no mouse-into-cell to scan + - listens on window, uses keyboard detection + - matrix approach have an opinionated but customizable approach to streamline workflows diff --git a/beam/docs/user/mobile/index.md b/beam/docs/user/mobile/index.md new file mode 100644 index 00000000..40309672 --- /dev/null +++ b/beam/docs/user/mobile/index.md @@ -0,0 +1,8 @@ + + +# Mobile + - Installing the PWA + - User setup and "Scan to Login" feature + - Basic navigation + - Scanner configuration \ No newline at end of file diff --git a/beam/docs/user/mobile/workflows.md b/beam/docs/user/mobile/workflows.md new file mode 100644 index 00000000..edba77e8 --- /dev/null +++ b/beam/docs/user/mobile/workflows.md @@ -0,0 +1,8 @@ + + +- Mobile Workflows + - Receiving + - Manufacturing + - Shipping + - Stock Transfer \ No newline at end of file diff --git a/beam/docs/listview.md b/beam/docs/user/scanning/index.md similarity index 57% rename from beam/docs/listview.md rename to beam/docs/user/scanning/index.md index edfd0484..6d5bb8b8 100644 --- a/beam/docs/listview.md +++ b/beam/docs/user/scanning/index.md @@ -1,28 +1,46 @@ - - -# Listview - -The result of scanning a barcode in the listview depends on several factors: - - - Is the barcode recognized? - - What doctype is it associated with? - -For example, when an Item is scanned while viewing the Item list, the user is routed to the record for that Item: - -| Scanned Doctype | Listview | Action | Target | -|-----------------|-----------------------|--------|--------| -|Item|Item|route|Item| - - -Another example: If an Item is scanned while viewing the Purchase Receipt list, a filter is added that shows the Delivery Notes with those items: - -| Scanned Doctype | Listview | Action | Target | -|-----------------|-----------------------|--------|--------| -|Item|Purchase Receipt|filter|item_code| - - -Beam uses a [decision matrix](./matrix.md) to decide what action to take based on what kind of doctype has been scanned. - -Custom actions and client side functions can be added by using [hooks](./hooks.md) - + + +# Listview + +The result of scanning a barcode in the listview depends on several factors: + + - Is the barcode recognized? + - What doctype is it associated with? + +For example, when an Item is scanned while viewing the Item list, the user is routed to the record for that Item: + +| Scanned Doctype | Listview | Action | Target | +|-----------------|-----------------------|--------|--------| +|Item|Item|route|Item| + + +Another example: If an Item is scanned while viewing the Purchase Receipt list, a filter is added that shows the Delivery Notes with those items: + +| Scanned Doctype | Listview | Action | Target | +|-----------------|-----------------------|--------|--------| +|Item|Purchase Receipt|filter|item_code| + + +Beam uses a [decision matrix](./matrix.md) to decide what action to take based on what kind of doctype has been scanned. + +Custom actions and client side functions can be added by using [hooks](./hooks.md) + + +# Form + +The result of scanning a barcode in the form depends on several factors: + + - Is the barcode recognized? + - What doctype is it associated with? + +For example, when an Item is scanned while viewing a Delivery Note record, it will add a row for that item if one doesn't exist, or increment the highest-indexed existing row with that Item's item_code in it. + +| Scanned Doctype | Form | Action | Target | +|-----------------|-----------------------|--------|--------| +|Item|Delivery Note|add_or_increment|item_code| + +Beam uses a [decision matrix](./matrix.md) to decide what action to take based on what kind of doctype has been scanned. + +Custom actions and client side functions can be added by using [hooks](./hooks.md). + diff --git a/beam/docs/matrix.md b/beam/docs/user/scanning/matrix.md similarity index 100% rename from beam/docs/matrix.md rename to beam/docs/user/scanning/matrix.md diff --git a/beam/docs/user/scanning/workflows.md b/beam/docs/user/scanning/workflows.md new file mode 100644 index 00000000..055a83a6 --- /dev/null +++ b/beam/docs/user/scanning/workflows.md @@ -0,0 +1,11 @@ + + +- Common Workflows + - Receiving goods + - Stock Transfers + - Sales Fulfillment + - Manufacturing + - Repack + - Stock Reconciliation + - Pick List \ No newline at end of file From 076384157b7ab6292c5055056e24559db920ff30 Mon Sep 17 00:00:00 2001 From: Rohan Bansal Date: Mon, 2 Jun 2025 17:51:42 +0530 Subject: [PATCH 2/2] docs: add developer documentation for Beam architecture --- beam/docs/developer/architecture/demand.md | 21 +++++ .../developer/architecture/development.md | 78 +++++++++++++++++++ beam/docs/developer/architecture/overview.md | 53 +++++++++++++ beam/docs/developer/extending_beam.md | 52 +++++++++---- beam/docs/developer/index.md | 25 ++++++ 5 files changed, 212 insertions(+), 17 deletions(-) create mode 100644 beam/docs/developer/architecture/demand.md create mode 100644 beam/docs/developer/architecture/development.md create mode 100644 beam/docs/developer/architecture/overview.md diff --git a/beam/docs/developer/architecture/demand.md b/beam/docs/developer/architecture/demand.md new file mode 100644 index 00000000..333af3ef --- /dev/null +++ b/beam/docs/developer/architecture/demand.md @@ -0,0 +1,21 @@ +## Demand Design + +### SQLite +Beam uses SQLite in parallel with MariaDB for specific data separation and performance optimization. + +**Architecture Pattern:** +- Beam maintains dual database connections: + - MariaDB (via Frappe): Core ERP data, transactions, master data + - SQLite: Demand planning, receiving operations, analytics + +**Demand and Receiving Tables:** +- **Demand Planning Data**: SQLite stores demand forecasting calculations and planning data +- **Receiving Operations**: Real-time receiving data and processing queues +- **Separation of Concerns**: Isolates high-frequency demand operations from core ERP data +- **Performance Benefits**: Faster read/write operations for demand-specific workloads + +**Use Cases:** +- Demand forecasting calculations +- Receiving workflow data +- Temporary processing queues +- Analytics and reporting aggregations diff --git a/beam/docs/developer/architecture/development.md b/beam/docs/developer/architecture/development.md new file mode 100644 index 00000000..b1b2fa2f --- /dev/null +++ b/beam/docs/developer/architecture/development.md @@ -0,0 +1,78 @@ +## Development Guide + +### Setup + +**Prerequisites:** +```bash +# Frappe Framework requirements +python >= 3.8 +node >= 16.x +npm >= 8.x +mariadb >= 10.3 +redis-server + +# For development with SQLite +sqlite3 +``` + +**Frappe Bench Installation:** +```bash +# Install Frappe bench +pip install frappe-bench + +# Create new site +bench new-site beam.local +bench get-app beam https://github.com/agritheory/beam.git +bench --site beam.local install-app beam + +# Start development +bench start +``` + +**Frontend Development Setup:** +```bash +# Navigate to Beam app +cd apps/beam + +# Install Node dependencies +npm install + +# Start Vite development server with HMR +npm run dev + +# Build for production +npm run build + +# Register Beam resolvers +npm run register +``` + +**Environment Configuration:** +```python +# site_config.json +{ + "db_name": "beam_development", + "db_password": "password", + "developer_mode": 1, + "auto_reload": 1, + "disable_website_cache": 1 +} +``` + +**Development Workflow:** +```bash +# Backend development (Python/Frappe) +bench start + +# Frontend development (Vue/TypeScript) +npm run dev + +# Watch mode for frontend builds +npm run build:watch +``` + +**Scan Matrix Development:** +- Edit `/beam/scan/__init__.py` for scan logic +- Modify `listview` and `frm` dictionaries for action definitions +- Use `beam_listview` and `beam_frm` hooks for custom overrides +- Test scan actions via Beam PWA interface diff --git a/beam/docs/developer/architecture/overview.md b/beam/docs/developer/architecture/overview.md new file mode 100644 index 00000000..4614686f --- /dev/null +++ b/beam/docs/developer/architecture/overview.md @@ -0,0 +1,53 @@ +## Beam System Overview + +### Component Structure +Beam's Vue.js PWA frontend is built with modular components using the Stonecrop library: + +**Core Vue Components:** +- **Scan Components**: Barcode scanning interface components +- **Form Components**: Dynamic form rendering using @stonecrop/aform +- **List Components**: Data listing and filtering components +- **Navigation Components**: PWA navigation and routing +- **Mobile Components**: Touch-optimized mobile interfaces + +**Stonecrop Integration:** +- `@stonecrop/beam` - Core Beam-specific components +- `@stonecrop/aform` - Advanced form handling components + +### Decision Matrix +Beam's scan matrix system defines actions and responses based on both the barcode scanned and the current context (list view or form). This allows for dynamic behavior based on user interactions. + +The response action is determined by: +- **Barcode Type**: Item, Handling Unit, Warehouse, etc. +- **Current Context**: Whether the scan occurs in a list view or a form +- **Target Doctype**: The document type being interacted with +- **Current Document State**: Whether the document is new, draft, or submitted +- **Custom Hooks**: Overrides defined in the `hooks.py` file + +The default scan matrix defines the following actions: + +**List View Actions:** +- **Filter Actions**: Apply filters to list views based on scanned items +- **Route Actions**: Navigate to specific document views + +**Form Actions:** +- **`add_or_increment`**: Add new items or increment existing quantities +- **`add_or_associate`**: Associate scanned items with form fields +- **`set_item_code_and_handling_unit`**: Set item and handling unit fields +- **`set_warehouse`**: Set warehouse fields + +### Built-in Functions + +**Form Functions:** +- `scan()` - The public API endpoint for handling barcode scans +- `get_barcode_context()` - Resolve barcode to document context +- `get_handling_unit()` - Retrieve handling unit details +- `get_stock_entry_item_details()` - Stock entry specific item processing +- `get_list_action()` - Generate list view actions +- `get_form_action()` - Generate form actions + +**Mobile Functions:** +- PWA offline capabilities via Workbox +- OnScan.js integration for barcode scanning +- Vue Toast notifications for user feedback +- Pinia state management for offline data sync diff --git a/beam/docs/developer/extending_beam.md b/beam/docs/developer/extending_beam.md index 58d14886..bf8bba42 100644 --- a/beam/docs/developer/extending_beam.md +++ b/beam/docs/developer/extending_beam.md @@ -3,23 +3,49 @@ For license information, please see license.txt--> # Extending BEAM +### Schema / Hooks +Beam extends Frappe's hook system with custom hooks for different contexts: -## Custom Hooks +**Beam-specific Hooks:** +- **`beam_client`**: Additional client-side functions +- **`beam_listview`**: Custom list view scan actions +- **`beam_frm`**: Custom form scan actions +- **`beam_mobile`**: Custom mobile-specific components and route definitions +- **`demand`**: Demand planning and forecasting hooks -Beam can be extended by adding configurations to your application's `hooks.py`. - -To make scanning available on a custom doctype, add a table field for "Item Barcode" directly in the doctype or via customize form. Then add a key that is a peer with "Item" in the example below. +**Hook Override System:** +```python +# Custom scan actions for forms via hooks +beam_override = frappe.get_hooks("beam_frm") +override_doctype = beam_override.get(barcode_doc.doc.doctype) +override_action = override_doctype.get(context.frm) +``` -To extend scanning functionality within a doctype, add a key that is a peer with "Delivery Note" in the example below. +#### Examples ```python # hooks.py +# To make scanning available on a custom doctype, add a table field +# for "Item Barcode" directly in the doctype or via customize form. +# Then add a key that is a peer with "Item" in the example below. + +# To extend scanning functionality within a doctype, add a key that +# is a peer with "Delivery Note" in the example below. + beam_listview = { "Item": { "Delivery Note": [ - {"action": "filter", "doctype": "Delivery Note Item", "field": "item_code"}, - {"action": "filter", "doctype": "Packed Item", "field": "item_code"} + { + "action": "filter", + "doctype": "Delivery Note Item", + "field": "item_code" + }, + { + "action": "filter", + "doctype": "Packed Item", + "field": "item_code" + } ], }, ... @@ -44,17 +70,9 @@ beam_frm = { }, ... } -``` - -To add a custom JavaScript function, add the following hook to your application's `hooks.py`. An example implementation is available in the source code. - -```python -# hooks.py - -beam_client = { - "show_message": "custom_app.show_message" -} +# To add a custom JavaScript function, use the following hook: +beam_client = {"show_message": "custom_app.show_message"} ``` ## Adding Custom Vue Components diff --git a/beam/docs/developer/index.md b/beam/docs/developer/index.md index d39cf7e4..5b277be5 100644 --- a/beam/docs/developer/index.md +++ b/beam/docs/developer/index.md @@ -1,3 +1,28 @@ +## Beam Developer Documentation + +Welcome to the Beam developer documentation. This guide provides comprehensive information for developers working with the Beam application. + +### Documentation Structure + +- **[Architecture](./architecture/overview.md)** - System overview, demand design and development guide + - **[Overview](./architecture/overview.md)** - High-level architecture, components, and data flow + - **[Demand Design](./architecture/demand.md)** - Demand planning, forecasting, and scan action design + - **[Development](./architecture/development.md)** - Setup instructions, development workflow, and environment configuration +- **[Extending Beam](./extending_beam.md)** - Hook system, custom actions, and mobile development +- **[Print Integration](./print_integrations.md)** - Print server setup, ZPL development, and custom formats + +### Getting Help + +- Check the troubleshooting sections in each guide +- Review the examples and code samples + +### Contributing + +When contributing to Beam: +- Follow the established architecture patterns +- Use the hook system for extensions +- Add tests for new functionality +- Update documentation for new features