diff --git a/CHANGELOG.md b/CHANGELOG.md index 903e94f2..8c894c52 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ - # CHANGELOG 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 new file mode 100644 index 00000000..bf8bba42 --- /dev/null +++ b/beam/docs/developer/extending_beam.md @@ -0,0 +1,99 @@ + + +# Extending BEAM + +### Schema / Hooks +Beam extends Frappe's hook system with custom hooks for different contexts: + +**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 + +**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) +``` + +#### 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" + } + ], + }, + ... +} + +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, use the following hook: +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"}, + }, + ], +} + +``` diff --git a/beam/docs/developer/index.md b/beam/docs/developer/index.md new file mode 100644 index 00000000..5b277be5 --- /dev/null +++ b/beam/docs/developer/index.md @@ -0,0 +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 diff --git a/beam/docs/print_server.md b/beam/docs/developer/print_integrations.md similarity index 100% rename from beam/docs/print_server.md rename to beam/docs/developer/print_integrations.md diff --git a/beam/docs/form.md b/beam/docs/form.md deleted file mode 100644 index b4e6788f..00000000 --- a/beam/docs/form.md +++ /dev/null @@ -1,19 +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/hooks.md b/beam/docs/hooks.md deleted file mode 100644 index f6cedbf4..00000000 --- a/beam/docs/hooks.md +++ /dev/null @@ -1,52 +0,0 @@ - - -# 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" -} - -``` diff --git a/beam/docs/testing.md b/beam/docs/testing.md deleted file mode 100644 index 04d877a2..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 100% rename from beam/docs/handling_unit.md rename to beam/docs/user/handling_units/index.md 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 58% rename from beam/docs/listview.md rename to beam/docs/user/scanning/index.md index 2b47c8e4..e8bf6b3f 100644 --- a/beam/docs/listview.md +++ b/beam/docs/user/scanning/index.md @@ -25,3 +25,21 @@ Another example: If an Item is scanned while viewing the Purchase Receipt list, 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