### Setup POS Next for Development

Source: https://github.com/brainwise-dev/posnext/blob/develop/README.md

Sets up POS Next in development mode. This involves getting the app, installing frontend dependencies, and running development servers.

```bash
cd ~/frappe-bench
bench get-app /path/to/pos_next
cd apps/pos_next/POS
npm install
npm run dev
bench start
```

--------------------------------

### Install POS Next (Fresh)

Source: https://github.com/brainwise-dev/posnext/blob/develop/README.md

Installs the POS Next app from GitHub for a fresh installation. Ensure you are in your Frappe bench directory.

```bash
cd ~/frappe-bench
bench get-app https://github.com/BrainWise-DEV/pos_next.git --branch version-15
bench --site [your-site-name] install-app pos_next
bench --site [your-site-name] migrate
bench build --app pos_next
bench restart
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/brainwise-dev/posnext/blob/develop/README.md

Command to navigate to the app directory and install pre-commit hooks for code quality.

```bash
cd apps/pos_next && pre-commit install
```

--------------------------------

### Clone and Initialize Project

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS/README.md

Commands to clone the starter template into an existing Frappe app directory and install dependencies.

```bash
cd apps/todo
npx degit NagariaHussain/doppio_frappeui_starter frontend
cd frontend
yarn
yarn dev
```

--------------------------------

### Start Backend Server

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS/OFFLINE_IMPLEMENTATION_COMPLETE.md

Use this bash command to restart the backend server after testing offline functionality.

```bash
bench start
```

--------------------------------

### Item-Level Discount Example

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/PRICING_AND_SUBMISSION.md

Shows how a pricing rule is applied to an individual item.

```text
Item: Laptop
Original: $1,000
Discount: 15% (from "Summer Sale" pricing rule)
Final: $850
```

--------------------------------

### Verify Version Setup

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/QUICKSTART_VERSION.md

Check for the existence of all version-related files and verify that the version numbers match across different configuration files.

```bash
# Check all version files exist
ls -la pos_next/__init__.py
ls -la POS/package.json
ls -la pos_next/public/pos/version.json

# Check versions match
grep "__version__" pos_next/__init__.py
grep "version" POS/package.json
cat pos_next/public/pos/version.json
```

--------------------------------

### Cart-Level Discount Example

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/PRICING_AND_SUBMISSION.md

Shows how a coupon is applied to the entire cart subtotal.

```text
Subtotal: $500
Coupon "SAVE50": -$50
New Subtotal: $450
```

--------------------------------

### Verify background sync initiation

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/LARGE_CATALOG_OPTIMIZATION.md

Check the console for this specific log message to confirm the background sync process has started.

```text
Starting AGGRESSIVE background sync
```

--------------------------------

### Get Build and App Versions (Python)

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/VERSION_CONTROL.md

Use these utility functions to retrieve the current build version for cache busting and the application version. Ensure the `pos_next.utils` module is imported.

```python
from pos_next.utils import get_build_version, get_app_version

# Get current build version for cache busting
build_ver = get_build_version()  # Returns: "1730043123456"

# Get application version
app_ver = get_app_version()      # Returns: "1.0.0"
```

--------------------------------

### GET pos_next.api.offers.get_offers

Source: https://github.com/brainwise-dev/posnext/blob/develop/README.md

Retrieves available promotional offers for a specific POS profile and customer.

```APIDOC
## GET pos_next.api.offers.get_offers

### Description
Retrieves a list of available offers based on the provided POS profile and customer identifier.

### Parameters
#### Request Body
- **pos_profile** (string) - Required - The name of the POS profile.
- **customer** (string) - Required - The customer identifier.

### Request Example
{
	"pos_profile": "Main POS",
	"customer": "CUST-00001"
}
```

--------------------------------

### Open/Closed Principle Example (Payment Strategy)

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS_MIGRATION_PLAN.md

Demonstrates the Open/Closed Principle using a Payment Strategy pattern in TypeScript. New payment methods can be added by implementing the PaymentStrategy interface without modifying existing classes.

```typescript
// Payment Strategy Pattern
interface PaymentStrategy {
  process(amount: number): Promise<PaymentResult>
}

class CashPayment implements PaymentStrategy { }
class CardPayment implements PaymentStrategy { }
class MobilePayment implements PaymentStrategy { }
```

--------------------------------

### Update POS Next

Source: https://github.com/brainwise-dev/posnext/blob/develop/README.md

Updates an existing POS Next installation to the latest version from the version-15 branch. Apply updates by migrating and rebuilding assets.

```bash
cd ~/frappe-bench/apps/pos_next
git pull origin version-15
cd ../..
bench --site [your-site-name] migrate
bench build --app pos_next
bench --site [your-site-name] clear-cache
bench restart
```

--------------------------------

### Start Aggressive Background Cache Sync

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/LARGE_CATALOG_OPTIMIZATION.md

Initiates a continuous background loop for syncing cache items in batches. Use this for faster, more frequent updates compared to interval-based sync.

```javascript
async function startBackgroundCacheSync(profile, filterGroups = []) {
    const batchSize = 500
    const BATCH_DELAY_MS = 500  // 500ms between batches

    // CONTINUOUS SYNC LOOP - much faster than interval-based!
    const syncLoop = async () => {
        while (cacheSyncing.value) {
            // Fetch batch
            const response = await call("pos_next.api.items.get_items", {
                pos_profile: profile,
                item_group: currentGroup,
                start: offset,
                limit: batchSize,
            })

            // Cache to IndexedDB
            await offlineWorker.cacheItems(list)

            // Update progress for UI
            cacheStats.value = {
                ...cacheStats.value,
                items: totalCached,
                lastSync: new Date().toISOString()
            }

            // Small delay to not overwhelm server
            await new Promise(resolve => setTimeout(resolve, BATCH_DELAY_MS))
        }
    }

    syncLoop()  // Runs in background
}
```

--------------------------------

### Get Customer Balance API

Source: https://github.com/brainwise-dev/posnext/blob/develop/CHANGELOG.md

Retrieves detailed customer balance information.

```APIDOC
## GET /api/customers/{customer_id}/balance

### Description
Returns detailed customer balance including total outstanding, total credit, and net balance. Calculates from Sales Invoices and Payment Entries. Supports company-specific filtering.

### Method
GET

### Endpoint
/api/customers/{customer_id}/balance

### Parameters
#### Path Parameters
- **customer_id** (string) - Required - The ID of the customer.

#### Query Parameters
- **company** (string) - Optional - Filter balance by a specific company.

### Response
#### Success Response (200)
- **total_outstanding** (number) - The total amount owed by the customer.
- **total_credit** (number) - The total available credit for the customer.
- **net_balance** (number) - The net balance (total_credit - total_outstanding).

#### Response Example
```json
{
  "total_outstanding": 150.75,
  "total_credit": 50.00,
  "net_balance": -100.75
}
```
```

--------------------------------

### Create New Report Directory Structure

Source: https://github.com/brainwise-dev/posnext/blob/develop/pos_next/pos_next/report/README.md

Initiate a new report by creating its directory and essential files: __init__.py, report_name.json, report_name.py, and report_name.js within the pos_next/pos_next/report/ directory.

```bash
pos_next/pos_next/report/new_report/
__init__.py
new_report.json
new_report.py
new_report.js
```

--------------------------------

### GET /api/wallet/info

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/Wallet-System-Technical-Guide.md

Retrieves comprehensive wallet configuration and status information for the POS frontend.

```APIDOC
## GET get_wallet_info

### Description
Returns detailed wallet status, balance, and loyalty program settings for a given customer and POS profile.

### Parameters
#### Query Parameters
- **customer** (string) - Required - The customer identifier.
- **company** (string) - Required - The company identifier.
- **pos_profile** (string) - Required - The POS profile identifier.

### Response
#### Success Response (200)
- **wallet_enabled** (boolean) - Whether the wallet feature is active.
- **wallet_exists** (boolean) - Whether the wallet record exists.
- **wallet_balance** (float) - Current balance.
- **wallet_name** (string) - The unique name of the wallet.
- **loyalty_program** (string) - Associated loyalty program name.

### Request Example
```python
from pos_next.api.wallet import get_wallet_info

info = get_wallet_info(
    customer="CUST-001",
    company="My Company",
    pos_profile="POS Profile"
)
```
```

--------------------------------

### Post Version Bump Steps

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/QUICKSTART_VERSION.md

After bumping the version, build the frontend to generate a new version.json, verify the build version, and then commit and tag the changes.

```bash
# 1. Build frontend (generates new version.json)
cd POS
yarn build

# 2. Verify build version
cat ../pos_next/public/pos/version.json

# 3. Commit and tag
git add .
git commit -m "chore: bump version to 1.0.1"
git tag v1.0.1
git push origin develop --tags
```

--------------------------------

### Create a New Release Workflow

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/QUICKSTART_VERSION.md

This sequence of commands outlines the process for creating a new release, including bumping the version, building the frontend, testing locally, and committing/tagging the release.

```bash
# 1. Bump version
./scripts/version-bump.sh patch

# 2. Build
cd POS && yarn build

# 3. Test locally
cd /home/ubuntu/frappe-bench
bench --site nexus.local execute pos_next.utils.get_build_version

# 4. Commit and tag
git add .
git commit -m "chore: release v1.0.1"
git tag v1.0.1
git push origin develop --tags
```

--------------------------------

### GET /api/wallet/balance

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/Wallet-System-Technical-Guide.md

Retrieves the available wallet balance for a specific customer within a company context.

```APIDOC
## GET get_customer_wallet_balance

### Description
Returns the available wallet balance for a customer, with an optional parameter to exclude specific invoice amounts.

### Parameters
#### Query Parameters
- **customer** (string) - Required - The customer identifier.
- **company** (string) - Required - The company identifier.
- **exclude_invoice** (string) - Optional - Invoice ID to exclude from balance calculation.

### Response
#### Success Response (200)
- **balance** (float) - The available wallet balance.

### Request Example
```python
from pos_next.api.wallet import get_customer_wallet_balance

balance = get_customer_wallet_balance(
    customer="CUST-001",
    company="My Company",
    exclude_invoice="SINV-001"
)
```
```

--------------------------------

### Offline ID Format Example

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/OFFLINE_SYNC.md

The standard format for unique offline identifiers used for deduplication.

```javascript
// Format: pos_offline_<uuid-v4>
// Example: pos_offline_a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
```

--------------------------------

### Data Pre-Loading System

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS/OFFLINE_IMPLEMENTATION_STATUS.md

Initializes the local cache by fetching items and customers from the server while online.

```javascript
// When POS opens (while online):
await cacheItemsFromServer(posProfile)    // Load all items
await cacheCustomersFromServer(posProfile) // Load all customers
await setSetting('cache_ready', true)      // Mark as ready
```

--------------------------------

### Enable Loyalty Program and Wallet in POS Settings

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/Wallet-System-Technical-Guide.md

Configure POS settings to enable the loyalty program and wallet features. Required fields include Loyalty Program and Wallet Account.

```text
POS Settings:
├── enable_loyalty_program: ✓
├── Loyalty Program: [Required - Select Program]
├── Wallet Account: [Required - Select Account]
├── auto_create_wallet: ✓ (automatic, read-only)
└── loyalty_to_wallet: ✓ (automatic, read-only)
```

--------------------------------

### GET /get_item_groups

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/LARGE_CATALOG_OPTIMIZATION.md

Retrieves the item groups configured for a specific POS Profile, including hierarchy information.

```APIDOC
## GET /get_item_groups

### Description
Get item groups configured in POS Profile with hierarchy info.

### Method
GET

### Endpoint
/get_item_groups

### Parameters
#### Query Parameters
- **pos_profile** (str) - Required - POS Profile name

### Response
#### Success Response (200)
- **list** (array) - List of objects containing item_group and child_groups
```

--------------------------------

### Build POS Next for Production

Source: https://github.com/brainwise-dev/posnext/blob/develop/README.md

Builds the POS Next application for production deployment. This includes building frontend assets and Frappe assets.

```bash
cd apps/pos_next/POS
npm run build
bench build --app pos_next
bench restart
```

--------------------------------

### Check Current Application and Build Versions

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/QUICKSTART_VERSION.md

Use these commands to retrieve the current application version and the build version (used for cache busting).

```bash
# Application version
cd /home/ubuntu/frappe-bench
bench --site nexus.local execute pos_next.utils.get_app_version
# Output: "1.0.0"
```

```bash
# Build version (for cache busting)
bench --site nexus.local execute pos_next.utils.get_build_version
# Output: "1730569908806"
```

--------------------------------

### Get Available Offers via Frappe API

Source: https://github.com/brainwise-dev/posnext/blob/develop/README.md

Retrieves a list of applicable offers for a specific customer and POS profile.

```python
frappe.call({
    method: 'pos_next.api.offers.get_offers',
    args: {
        pos_profile: 'Main POS',
        customer: 'CUST-00001'
    },
    callback: (r) => console.log(r.message)
})
```

--------------------------------

### Project File Structure

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/OFFLINE_SYNC.md

Overview of the directory structure for the offline sync module.

```text
POS/src/utils/offline/
├── uuid.js           # Shared UUID generation
├── sync.js           # Main sync logic
├── db.js             # IndexedDB schema
└── offlineState.js   # Connectivity state management

POS/src/workers/
└── offline.worker.js # Background processing

pos_next/api/
└── invoices.py       # Server-side API

pos_next/pos_next/doctype/offline_invoice_sync/
├── offline_invoice_sync.json  # DocType definition
└── offline_invoice_sync.py    # DocType class
```

--------------------------------

### GET /get_items_bulk

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/LARGE_CATALOG_OPTIMIZATION.md

Fetches items from multiple item groups in a single query, useful for bulk loading data into the POS interface.

```APIDOC
## GET /get_items_bulk

### Description
Fetch items from multiple item groups in a single query.

### Method
GET

### Endpoint
/get_items_bulk

### Parameters
#### Query Parameters
- **pos_profile** (str) - Required - POS Profile name
- **item_groups** (str) - Optional - JSON array of item group names
- **limit** (int) - Optional - Maximum items to return (default 2000)

### Response
#### Success Response (200)
- **list** (array) - Items from all specified groups (deduplicated)
```

--------------------------------

### Create Loyalty Program

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/Wallet-System-Technical-Guide.md

Set up a new loyalty program. Key settings include program name, conversion factor, and expense/collection accounts.

```text
Selling > Loyalty Program > New
├── Program Name: "POS Rewards"
├── Company: [Your Company]
├── Auto Opt In: ✓
├── Conversion Factor: 1.0
├── Expense Account: [Loyalty Expense Account]
└── Collection Rules:
    └── Tier: Base, Min Spent: 0, Factor: 1
```

--------------------------------

### Configure Vue Application

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/STARTUP_SEQUENCE.md

Initializes the Vue app instance with Pinia state management, plugins, and global components.

```javascript
const app = createApp(App)
const pinia = createPinia()

// Plugins
app.use(pinia)              // State management
app.use(resourcesPlugin)    // Frappe-UI resources
app.use(pageMetaPlugin)     // Page meta tags
app.use(translationPlugin)  // i18n support

// Global components (available in all templates without import)
app.component("Button", Button)
app.component("Dialog", Dialog)
app.component("Input", Input)
// ... etc
```

--------------------------------

### Cache Initialization on Startup

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS/OFFLINE_IMPLEMENTATION_STATUS.md

Initializes the memory cache and checks for readiness during application startup.

```javascript
// In App.vue or main.js
import { initMemoryCache, isCacheReady } from '@/utils/offline'

onMounted(async () => {
	await initMemoryCache()

	if (!isCacheReady()) {
		// Show warning: "POS needs to sync data for offline use"
		// Trigger sync if online
	}
})
```

--------------------------------

### Get or Create Wallet API

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/Wallet-System-Technical-Guide.md

Retrieves an existing wallet for a customer or creates a new one if it does not exist. This is useful for ensuring a wallet is available before performing wallet-related operations.

```python
from pos_next.api.wallet import get_or_create_wallet

wallet = get_or_create_wallet(
    customer="CUST-001",
    company="My Company"
)
# Returns: Wallet dict or document
```

--------------------------------

### Test Offer Application via Backend API

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/OFFERS_AND_PROMOTIONS.md

Invoke the apply_offers function to verify pricing rule calculations for a specific set of items and offers.

```python
from pos_next.api.invoices import apply_offers

result = apply_offers({
    "doctype": "Sales Invoice",
    "pos_profile": "Demo",
    "customer": "Walk-in Customer",
    "items": [
        {"item_code": "SKU010", "qty": 1, "rate": 15.00, "uom": "Nos"},
        {"item_code": "SKU003", "qty": 1, "rate": 299.00, "uom": "Nos"}
    ]
}, selected_offers=["PRLE-0003"])

print(result)
```

--------------------------------

### Define project file structure

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS/.claude.md

Standard directory layout for the POSNext project.

```text
POS/src/
├── components/
│   ├── sale/              # POS sale-related components
│   ├── shift/             # Shift management components
│   └── common/            # Shared components
├── composables/           # Vue composables (useOffline, useInvoice, etc.)
├── pages/                 # Main pages (POSSale, Login, Home)
├── utils/                 # Utility functions (.js files)
│   └── offline/          # Offline-specific utilities
└── router.js             # Vue Router configuration
```

--------------------------------

### Initialize Feature Branch

Source: https://github.com/brainwise-dev/posnext/blob/develop/README.md

Command to create a new feature branch for repository contributions.

```bash
git checkout -b feature/amazing-feature
```

--------------------------------

### Get Wallet Information API

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/Wallet-System-Technical-Guide.md

Fetches comprehensive wallet details suitable for display on the POS frontend. This includes wallet status, balance, and associated loyalty program information.

```python
from pos_next.api.wallet import get_wallet_info

info = get_wallet_info(
    customer="CUST-001",
    company="My Company",
    pos_profile="POS Profile"
)
# Returns: {
#     "wallet_enabled": True,
#     "wallet_exists": True,
#     "wallet_balance": 500.0,
#     "wallet_name": "CUST-001-WALLET",
#     "auto_create": True,
#     "loyalty_program": "POS Rewards",
#     "loyalty_to_wallet": True
# }
```

--------------------------------

### Get Customer Wallet Balance API

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/Wallet-System-Technical-Guide.md

Retrieves the available wallet balance for a given customer. The `exclude_invoice` parameter is optional and can be used to exclude a specific invoice from the balance calculation.

```python
from pos_next.api.wallet import get_customer_wallet_balance

balance = get_customer_wallet_balance(
    customer="CUST-001",
    company="My Company",
    exclude_invoice="SINV-001"  # Optional
)
# Returns: 500.0
```

--------------------------------

### Create Wallet Payment Method

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/Wallet-System-Technical-Guide.md

Configure a new payment mode for wallet transactions. Ensure 'Is Wallet Payment' is checked and the correct default account is assigned.

```text
Accounting > Mode of Payment > New
├── Mode of Payment: "Redeem Points"
├── Type: General
├── Is Wallet Payment: ✓ (REQUIRED!)
└── Accounts:
    └── Company: [Your Company]
        └── Default Account: Customer Wallet
```

--------------------------------

### Troubleshoot: Version Bump Script Fails

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/QUICKSTART_VERSION.md

If the version bump script fails, ensure it has execute permissions and then try running it again.

```bash
# Solution: Check file permissions
chmod +x scripts/version-bump.sh
./scripts/version-bump.sh patch
```

--------------------------------

### Get Item Group with Descendants (Python)

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/LARGE_CATALOG_OPTIMIZATION.md

Retrieves an item group and all its descendant groups using Frappe's nested set model. Useful for filtering items by a parent group and its children.

```python
def _get_item_group_with_descendants(item_group):
    """Get an item group and all its descendants using nested set model."""
    if not item_group:
        return []

    ItemGroup = DocType("Item Group")

    # Get the parent group's lft/rgt values
    group_data = (
        frappe.qb.from_(ItemGroup)
        .select(ItemGroup.lft, ItemGroup.rgt, ItemGroup.is_group)
        .where(ItemGroup.name == item_group)
        .run(as_dict=True)
    )

    if not group_data:
        return [item_group]

    group = group_data[0]
    if not group.is_group:
        return [item_group]

    # Get all descendants using nested set (lft/rgt)
    descendants = (
        frappe.qb.from_(ItemGroup)
        .select(ItemGroup.name)
        .where(ItemGroup.lft > group.lft)
        .where(ItemGroup.rgt < group.rgt)
        .run(pluck="name")
    )

    return [item_group] + list(descendants)
```

--------------------------------

### Liskov Substitution Principle Example (Invoice Hierarchy)

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS_MIGRATION_PLAN.md

Illustrates the Liskov Substitution Principle with an abstract base class for invoices and concrete implementations. Subclasses like SalesInvoice and POSInvoice can be used interchangeably with the base type.

```typescript
abstract class BaseInvoice {
  abstract calculate(): number
}

class SalesInvoice extends BaseInvoice { }
class POSInvoice extends BaseInvoice { }
```

--------------------------------

### Verify Build Version via Bench Console

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/VERSION_CONTROL.md

This command executes a Python function within the Frappe bench environment to retrieve the current build version of POS Next.

```bash
cd /home/ubuntu/frappe-bench
bench --site nexus.local execute pos_next.utils.get_build_version
```

--------------------------------

### Cache-First Data Loading

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS/OFFLINE_IMPLEMENTATION_STATUS.md

Demonstrates the current broken implementation versus the required cache-first logic.

```javascript
// In POSSale.vue - tries to fetch from server every time
const itemsResource = createResource({
	url: 'pos_next.api.invoices.get_items',
	// This FAILS when offline!
})
```

```javascript
// Should check cache first, server second
async function loadItems() {
	// If offline or cache exists, use cache
	if (isOffline() || isCacheReady()) {
		return await searchCachedItems()
	}

	// If online and cache stale, fetch from server
	if (needsCacheRefresh()) {
		await cacheItemsFromServer(posProfile)
	}

	return await searchCachedItems()
}
```

--------------------------------

### Troubleshoot: get_build_version Returns Fallback Format

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/QUICKSTART_VERSION.md

If `get_build_version` returns a fallback format like '1.0.0-timestamp', it indicates that `version.json` is missing. Rebuild the frontend to generate it.

```bash
# Solution: version.json is missing, rebuild frontend
cd POS
yarn build
```

--------------------------------

### Router and App Mounting

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/STARTUP_SEQUENCE.md

Registers the router and mounts the application instance to the DOM after authentication.

```javascript
app.use(router)
app.mount("#app")
```

--------------------------------

### Build Frontend with Custom Build Version

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/VERSION_CONTROL.md

This command shows how to build the frontend with a specific custom build version by setting the POS_NEXT_BUILD_VERSION environment variable before running the yarn build command.

```bash
cd POS
POS_NEXT_BUILD_VERSION=1.2.3 yarn build
```

--------------------------------

### Build Frontend Assets

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/README.md

Compiles the frontend application assets using Yarn.

```bash
cd POS
yarn build
```

--------------------------------

### Sync Configuration Settings

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/OFFLINE_SYNC.md

Global configuration constants for managing sync behavior, including retry limits and cleanup policies.

```javascript
const SYNC_CONFIG = {
    MAX_RETRY_COUNT: 3,      // Max sync retry attempts
    CLEANUP_AGE_DAYS: 7,     // Days to keep synced invoices
    PING_TIMEOUT_MS: 3000,   // Server ping timeout
}
```

--------------------------------

### Bump Application Version using Script

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/VERSION_CONTROL.md

These bash commands demonstrate how to use the version-bump.sh script to increment the patch, minor, or major version of the POS Next application. This script updates relevant files like __init__.py and package.json.

```bash
cd /home/ubuntu/frappe-bench/apps/pos_next

# Bump patch version (1.0.0 → 1.0.1)
./scripts/version-bump.sh patch

# Bump minor version (1.0.1 → 1.1.0)
./scripts/version-bump.sh minor

# Bump major version (1.1.0 → 2.0.0)
./scripts/version-bump.sh major
```

--------------------------------

### Check Application Version

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/README.md

Executes the utility function to retrieve the current version of the POS Next application within the Frappe bench environment.

```bash
cd /home/ubuntu/frappe-bench
bench --site nexus.local execute pos_next.utils.get_app_version
```

--------------------------------

### Verify Build Version via Python Script

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/VERSION_CONTROL.md

This Python script retrieves and prints the current build version of POS Next by importing the utility function. It includes necessary path manipulation to find the module.

```python
import sys
sys.path.insert(0, 'apps/pos_next')
from pos_next.utils import get_build_version
print(get_build_version())
```

--------------------------------

### Python API for Applying Offers in POS Next

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/OFFERS_AND_PROMOTIONS.md

This Python function, located in `pos_next/api/invoices.py`, calculates and applies promotional offers using ERPNext's Pricing Rules. It accepts invoice data and an optional list of specific offers to apply.

```python
@frappe.whitelist()
def apply_offers(invoice_data, selected_offers=None):
    """Calculate and apply promotional offers using ERPNext Pricing Rules."""
```

--------------------------------

### Create Wallet Account in Chart of Accounts

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/Wallet-System-Technical-Guide.md

Add a new 'Customer Wallet' account under Assets > Receivables. This account type is crucial for tracking wallet balances.

```text
Accounting > Chart of Accounts
├── Assets
│   └── Receivables
│       └── Add Child: "Customer Wallet"
│           ├── Account Type: Receivable
│           └── Is Group: No
```

--------------------------------

### Data Migration Script (Python)

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS_MIGRATION_PLAN.md

A Python script for migrating data from a previous system ('POS Awesome') to the new system. It includes functions to migrate custom fields, DocTypes, and general data like shifts, offers, and coupons.

```python
# migrate_pos_awesome_to_next.py
def migrate_custom_fields():
    """Migrate all custom fields from POS Awesome"""
    fields = get_pos_awesome_custom_fields()
    for field in fields:
        create_custom_field(field)

def migrate_doctypes():
    """Migrate custom DocTypes"""
    doctypes = ['POS Opening Shift', 'POS Closing Shift', ...]
    for doctype in doctypes:
        migrate_doctype(doctype)

def migrate_data():
    """Migrate existing data"""
    # Migrate shifts
    # Migrate offers
    # Migrate coupons

```

--------------------------------

### Create Items Composable

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS_SALE_INTEGRATION_PLAN.md

Handles item fetching, searching, and barcode scanning. Requires a posProfile to initialize data fetching.

```javascript
import { ref, computed } from 'vue'
import { createResource } from 'frappe-ui'

export function useItems(posProfile) {
  const items = ref([])
  const searchTerm = ref('')
  const selectedItemGroup = ref(null)

  const itemsResource = createResource({
    url: 'pos_next.api.invoices.get_items',
    params: {
      pos_profile: posProfile,
      search_term: searchTerm.value,
      item_group: selectedItemGroup.value,
    },
    auto: true,
    onSuccess(data) {
      items.value = data
    }
  })

  const searchByBarcodeResource = createResource({
    url: 'pos_next.api.items.search_by_barcode',
    auto: false,
  })

  const filteredItems = computed(() => {
    if (!searchTerm.value) return items.value

    const term = searchTerm.value.toLowerCase()
    return items.value.filter(item =>
      item.item_name.toLowerCase().includes(term) ||
      item.item_code.toLowerCase().includes(term)
    )
  })

  async function searchByBarcode(barcode) {
    const result = await searchByBarcodeResource.submit({
      barcode,
      pos_profile: posProfile
    })
    return result
  }

  function refreshItems() {
    itemsResource.reload()
  }

  return {
    items,
    filteredItems,
    searchTerm,
    selectedItemGroup,
    searchByBarcode,
    refreshItems,
    itemsResource,
  }
}
```

--------------------------------

### Stop Backend Server for Testing

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS/OFFLINE_IMPLEMENTATION_STATUS.md

To test the offline functionality, you can stop the backend server using the `bench stop` command. This simulates a complete loss of connectivity.

```bash
cd /home/ubuntu/frappe-bench
bench stop
```

--------------------------------

### Implement Repository Pattern

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS_MIGRATION_PLAN.md

Provides an abstraction layer for data access, supporting both Frappe API and offline storage implementations.

```typescript
interface IItemRepository {
  find(id: string): Promise<Item>
  search(query: string): Promise<Item[]>
  save(item: Item): Promise<void>
}

class ItemRepository implements IItemRepository {
  // Implementation using Frappe API
}

class OfflineItemRepository implements IItemRepository {
  // Implementation using IndexedDB
}
```

--------------------------------

### Integrate Version Hooks in Python

Source: https://github.com/brainwise-dev/posnext/blob/develop/docs/VERSION_CONTROL.md

This Python code demonstrates how to integrate build versions into asset URLs using hooks. It retrieves the build version and appends it as a query parameter for cache busting.

```python
_asset_version = get_build_version()
# app_include_js = f"/assets/pos_next/js/app.js?v={_asset_version}"
```

--------------------------------

### Configure Site Settings

Source: https://github.com/brainwise-dev/posnext/blob/develop/POS/README.md

Required configuration for site_config.json to bypass CSRF errors during local development.

```json
"ignore_csrf": 1
```

--------------------------------

### Clear Cache and Build App

Source: https://github.com/brainwise-dev/posnext/blob/develop/pos_next/pos_next/report/README.md

Troubleshoot reports not appearing by clearing Frappe cache and rebuilding the application. Navigate to the Frappe bench directory and execute the commands.

```bash
cd /home/ubuntu/frappe-bench
bench --site [site-name] clear-cache
bench build --app pos_next
```