mirror of
https://github.com/SpudGunMan/meshing-around.git
synced 2026-08-06 17:03:04 +02:00
Add comprehensive documentation for inventory and enhanced checklist
Co-authored-by: SpudGunMan <12676665+SpudGunMan@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
+138
-2
@@ -10,6 +10,7 @@ This document provides an overview of all modules available in the Mesh-Bot proj
|
||||
- [Games](#games)
|
||||
- [BBS (Bulletin Board System)](#bbs-bulletin-board-system)
|
||||
- [Checklist](#checklist)
|
||||
- [Inventory & Point of Sale](#inventory--point-of-sale)
|
||||
- [Location & Weather](#location--weather)
|
||||
- [Map Command](#map-command)
|
||||
- [EAS & Emergency Alerts](#eas--emergency-alerts)
|
||||
@@ -127,13 +128,148 @@ more at [meshBBS: How-To & API Documentation](bbstools.md)
|
||||
|
||||
## Checklist
|
||||
|
||||
### Enhanced Check-in/Check-out System
|
||||
|
||||
The checklist module provides asset tracking and accountability features with safety monitoring capabilities.
|
||||
|
||||
#### Basic Commands
|
||||
|
||||
| Command | Description |
|
||||
|--------------|-----------------------------------------------|
|
||||
| `checkin` | Check in a node/asset |
|
||||
| `checkout` | Check out a node/asset |
|
||||
| `checklist` | Show checklist database |
|
||||
| `checklist` | Show active check-ins |
|
||||
| `purgein` | Delete your check-in record |
|
||||
| `purgeout` | Delete your check-out record |
|
||||
|
||||
Enable in `[checklist]` section of `config.ini`.
|
||||
#### Advanced Features
|
||||
|
||||
- **Safety Monitoring with Time Intervals**
|
||||
- Check in with an expected interval: `checkin 60 Hunting in tree stand`
|
||||
- The system will track if you don't check back in within the specified time (in minutes)
|
||||
- Ideal for solo activities, remote work, or safety accountability
|
||||
|
||||
- **Approval Workflow**
|
||||
- `checklistapprove <id>` - Approve a pending check-in (admin)
|
||||
- `checklistdeny <id>` - Deny/remove a check-in (admin)
|
||||
|
||||
#### Examples
|
||||
|
||||
```
|
||||
# Basic check-in
|
||||
checkin Arrived at campsite
|
||||
|
||||
# Check-in with 30-minute monitoring interval
|
||||
checkin 30 Solo hiking on north trail
|
||||
|
||||
# Check out when done
|
||||
checkout Heading back to base
|
||||
|
||||
# View all active check-ins
|
||||
checklist
|
||||
```
|
||||
|
||||
#### Configuration
|
||||
|
||||
Enable in `[checklist]` section of `config.ini`:
|
||||
|
||||
```ini
|
||||
[checklist]
|
||||
enabled = True
|
||||
checklist_db = data/checklist.db
|
||||
reverse_in_out = False
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Inventory & Point of Sale
|
||||
|
||||
### Complete Inventory Management System
|
||||
|
||||
The inventory module provides a full point-of-sale (POS) system with inventory tracking, cart management, and transaction logging.
|
||||
|
||||
#### Item Management Commands
|
||||
|
||||
| Command | Description |
|
||||
|--------------|-----------------------------------------------|
|
||||
| `itemadd <name> <price> <qty> [location]` | Add new item to inventory |
|
||||
| `itemremove <name>` | Remove item from inventory |
|
||||
| `itemreset <name> [price=X] [qty=Y]` | Update item price or quantity |
|
||||
| `itemsell <name> <qty> [notes]` | Quick sale (bypasses cart) |
|
||||
| `itemreturn <transaction_id>` | Reverse a transaction |
|
||||
| `itemlist` | View all inventory items |
|
||||
| `itemstats` | View today's sales statistics |
|
||||
|
||||
#### Cart Commands
|
||||
|
||||
| Command | Description |
|
||||
|--------------|-----------------------------------------------|
|
||||
| `cartadd <name> <qty>` | Add item to your cart |
|
||||
| `cartremove <name>` | Remove item from cart |
|
||||
| `cartlist` or `cart` | View your cart |
|
||||
| `cartbuy` or `cartsell` | Complete transaction |
|
||||
| `cartclear` | Empty your cart |
|
||||
|
||||
#### Features
|
||||
|
||||
- **Transaction Tracking**: All sales are logged with timestamps and user information
|
||||
- **Cart Management**: Build up orders before completing transactions
|
||||
- **Penny Rounding**: Optional rounding for cash sales (USA mode)
|
||||
- Cash sales round down
|
||||
- Taxed sales round up
|
||||
- **Hot Item Stats**: Track best-selling items
|
||||
- **Location Tracking**: Optional warehouse/location field for items
|
||||
- **Transaction History**: Full audit trail of all sales and returns
|
||||
|
||||
#### Examples
|
||||
|
||||
```
|
||||
# Add items to inventory
|
||||
itemadd Radio 149.99 5 Shelf-A
|
||||
itemadd Battery 12.50 20 Warehouse-B
|
||||
|
||||
# View inventory
|
||||
itemlist
|
||||
|
||||
# Add items to cart
|
||||
cartadd Radio 2
|
||||
cartadd Battery 4
|
||||
|
||||
# View cart
|
||||
cartlist
|
||||
|
||||
# Complete sale
|
||||
cartsell Customer purchase
|
||||
|
||||
# Quick sale without cart
|
||||
itemsell Battery 1 Emergency sale
|
||||
|
||||
# View today's stats
|
||||
itemstats
|
||||
|
||||
# Process a return
|
||||
itemreturn 123
|
||||
```
|
||||
|
||||
#### Configuration
|
||||
|
||||
Enable in `[inventory]` section of `config.ini`:
|
||||
|
||||
```ini
|
||||
[inventory]
|
||||
enabled = True
|
||||
inventory_db = data/inventory.db
|
||||
# Set to True to enable penny rounding for USA cash sales
|
||||
disable_penny = False
|
||||
```
|
||||
|
||||
#### Database Schema
|
||||
|
||||
The system uses SQLite with four tables:
|
||||
- **items**: Product inventory
|
||||
- **transactions**: Sales records
|
||||
- **transaction_items**: Line items for each transaction
|
||||
- **carts**: Temporary shopping carts
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,388 @@
|
||||
# Enhanced Check-in/Check-out System
|
||||
|
||||
## Overview
|
||||
|
||||
The enhanced checklist module provides asset tracking and accountability features with advanced safety monitoring capabilities. This system is designed for scenarios where tracking people, equipment, or assets is critical for safety, accountability, or logistics.
|
||||
|
||||
## Key Features
|
||||
|
||||
### 🔐 Basic Check-in/Check-out
|
||||
- Simple interface for tracking when people or assets are checked in or out
|
||||
- Automatic duration calculation
|
||||
- Location tracking (GPS coordinates if available)
|
||||
- Notes support for additional context
|
||||
|
||||
### ⏰ Safety Monitoring with Time Intervals
|
||||
- Set expected check-in intervals for safety monitoring
|
||||
- Automatic tracking of overdue check-ins
|
||||
- Ideal for solo activities, remote work, or high-risk operations
|
||||
- Get alerts when someone hasn't checked in within their expected timeframe
|
||||
|
||||
### ✅ Approval Workflow
|
||||
- Admin approval system for check-ins
|
||||
- Deny/remove unauthorized check-ins
|
||||
- Maintain accountability and control
|
||||
|
||||
### 📍 Location Tracking
|
||||
- Automatic GPS location capture when checking in/out
|
||||
- View last known location in checklist
|
||||
- Track movement over time
|
||||
|
||||
## Configuration
|
||||
|
||||
Add to your `config.ini`:
|
||||
|
||||
```ini
|
||||
[checklist]
|
||||
enabled = True
|
||||
checklist_db = data/checklist.db
|
||||
# Set to True to reverse the meaning of checkin/checkout
|
||||
reverse_in_out = False
|
||||
```
|
||||
|
||||
## Commands Reference
|
||||
|
||||
### Basic Commands
|
||||
|
||||
#### Check In
|
||||
```
|
||||
checkin [interval] [notes]
|
||||
```
|
||||
|
||||
Check in to the system. Optionally specify a monitoring interval in minutes.
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
checkin Arrived at base camp
|
||||
checkin 30 Solo hiking on north trail
|
||||
checkin 60 Working alone in tree stand
|
||||
checkin Going hunting
|
||||
```
|
||||
|
||||
#### Check Out
|
||||
```
|
||||
checkout [notes]
|
||||
```
|
||||
|
||||
Check out from the system. Shows duration since check-in.
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
checkout Heading back
|
||||
checkout Mission complete
|
||||
checkout
|
||||
```
|
||||
|
||||
#### View Checklist
|
||||
```
|
||||
checklist
|
||||
```
|
||||
|
||||
Shows all active check-ins with durations.
|
||||
|
||||
**Example Response:**
|
||||
```
|
||||
ID: Hunter1 checked-In for 01:23:45📝Solo hunting
|
||||
ID: Tech2 checked-In for 00:15:30📝Equipment repair
|
||||
```
|
||||
|
||||
#### Purge Records
|
||||
```
|
||||
purgein # Delete your check-in record
|
||||
purgeout # Delete your check-out record
|
||||
```
|
||||
|
||||
Use these to manually remove your records if needed.
|
||||
|
||||
### Admin Commands
|
||||
|
||||
#### Approve Check-in
|
||||
```
|
||||
checklistapprove <checkin_id>
|
||||
```
|
||||
|
||||
Approve a pending check-in (requires admin privileges).
|
||||
|
||||
**Example:**
|
||||
```
|
||||
checklistapprove 123
|
||||
```
|
||||
|
||||
#### Deny Check-in
|
||||
```
|
||||
checklistdeny <checkin_id>
|
||||
```
|
||||
|
||||
Deny and remove a check-in (requires admin privileges).
|
||||
|
||||
**Example:**
|
||||
```
|
||||
checklistdeny 456
|
||||
```
|
||||
|
||||
## Safety Monitoring Feature
|
||||
|
||||
### How Time Intervals Work
|
||||
|
||||
When checking in with an interval parameter, the system will track whether you check in again or check out within that timeframe.
|
||||
|
||||
```
|
||||
checkin 60 Hunting in remote area
|
||||
```
|
||||
|
||||
This tells the system:
|
||||
- You're checking in now
|
||||
- You expect to check in again or check out within 60 minutes
|
||||
- If 60 minutes pass without activity, you'll be marked as overdue
|
||||
|
||||
### Use Cases for Time Intervals
|
||||
|
||||
1. **Solo Activities**: Hunting, hiking, or working alone
|
||||
```
|
||||
checkin 30 Solo patrol north sector
|
||||
```
|
||||
|
||||
2. **High-Risk Operations**: Tree work, equipment maintenance
|
||||
```
|
||||
checkin 45 Climbing tower for antenna work
|
||||
```
|
||||
|
||||
3. **Remote Work**: Working in isolated areas
|
||||
```
|
||||
checkin 120 Survey work in remote canyon
|
||||
```
|
||||
|
||||
4. **Check-in Points**: Regular status updates during long operations
|
||||
```
|
||||
checkin 15 Descending cliff face
|
||||
```
|
||||
|
||||
### Overdue Check-ins
|
||||
|
||||
The system tracks all check-ins with time intervals and can identify who is overdue. While the module provides the data, integration with the bot's alert system can send notifications when someone becomes overdue.
|
||||
|
||||
## Practical Examples
|
||||
|
||||
### Example 1: Hunting Scenario
|
||||
|
||||
Hunter checks in before going into the field:
|
||||
```
|
||||
checkin 60 Hunting deer stand #3, north 40
|
||||
```
|
||||
|
||||
System response:
|
||||
```
|
||||
Checked✅In: Hunter1 (monitoring every 60min)
|
||||
```
|
||||
|
||||
If the hunter doesn't check out or check in again within 60 minutes, they will appear on the overdue list.
|
||||
|
||||
When done hunting:
|
||||
```
|
||||
checkout Heading back to camp
|
||||
```
|
||||
|
||||
System response:
|
||||
```
|
||||
Checked⌛️Out: Hunter1 duration 02:15:30
|
||||
```
|
||||
|
||||
### Example 2: Emergency Response Team
|
||||
|
||||
Team leader tracks team members:
|
||||
|
||||
```
|
||||
# Team members check in
|
||||
checkin 30 Search grid A-1
|
||||
checkin 30 Search grid A-2
|
||||
checkin 30 Search grid A-3
|
||||
```
|
||||
|
||||
Team leader views status:
|
||||
```
|
||||
checklist
|
||||
```
|
||||
|
||||
Response shows all active searchers with their durations.
|
||||
|
||||
### Example 3: Equipment Checkout
|
||||
|
||||
Track equipment loans:
|
||||
|
||||
```
|
||||
checkin Radio #5 for field ops
|
||||
```
|
||||
|
||||
When equipment is returned:
|
||||
```
|
||||
checkout Equipment returned
|
||||
```
|
||||
|
||||
### Example 4: Site Survey
|
||||
|
||||
Field technicians checking in at locations:
|
||||
|
||||
```
|
||||
# At first site
|
||||
checkin 45 Site survey tower location 1
|
||||
|
||||
# Moving to next site (automatically checks out from first)
|
||||
checkin 45 Site survey tower location 2
|
||||
```
|
||||
|
||||
## Integration with Other Systems
|
||||
|
||||
### Geo-Location Awareness
|
||||
|
||||
The checklist system automatically captures GPS coordinates when available. This can be used for:
|
||||
- Tracking last known position
|
||||
- Geo-fencing applications
|
||||
- Emergency response coordination
|
||||
- Asset location management
|
||||
|
||||
### Alert Systems
|
||||
|
||||
The overdue check-in feature can trigger:
|
||||
- Notifications to supervisors
|
||||
- Emergency alerts
|
||||
- Automated messages to response teams
|
||||
- Email/SMS notifications (if configured)
|
||||
|
||||
### Scheduling Integration
|
||||
|
||||
Combine with the scheduler module to:
|
||||
- Send reminders to check in
|
||||
- Automatically generate reports
|
||||
- Schedule periodic check-in requirements
|
||||
- Send daily summaries
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For Users
|
||||
|
||||
1. **Always Include Context**: Add notes when checking in
|
||||
```
|
||||
checkin 30 North trail maintenance
|
||||
```
|
||||
Not just:
|
||||
```
|
||||
checkin
|
||||
```
|
||||
|
||||
2. **Set Realistic Intervals**: Don't set intervals too short or too long
|
||||
- Too short: False alarms
|
||||
- Too long: Defeats safety purpose
|
||||
|
||||
3. **Check Out Promptly**: Always check out when done to clear your status
|
||||
|
||||
4. **Use Consistent Naming**: If tracking equipment, use consistent names
|
||||
|
||||
### For Administrators
|
||||
|
||||
1. **Review Checklist Regularly**: Monitor who is checked in
|
||||
```
|
||||
checklist
|
||||
```
|
||||
|
||||
2. **Respond to Overdue Situations**: Act on overdue check-ins promptly
|
||||
|
||||
3. **Set Clear Policies**: Establish when and how to use the system
|
||||
|
||||
4. **Train Users**: Ensure everyone knows how to use time intervals
|
||||
|
||||
5. **Test the System**: Regularly verify the system is working
|
||||
|
||||
## Safety Scenarios
|
||||
|
||||
### Scenario 1: Tree Stand Hunting
|
||||
```
|
||||
checkin 60 Hunting from tree stand at north plot
|
||||
```
|
||||
If hunter falls or has medical emergency, they'll be marked overdue after 60 minutes.
|
||||
|
||||
### Scenario 2: Equipment Maintenance
|
||||
```
|
||||
checkin 30 Generator maintenance at remote site
|
||||
```
|
||||
If technician encounters danger, overdue status triggers response.
|
||||
|
||||
### Scenario 3: Hiking
|
||||
```
|
||||
checkin 120 Day hike to mountain peak
|
||||
```
|
||||
Longer interval for extended activity, but still provides safety net.
|
||||
|
||||
### Scenario 4: Watchstanding
|
||||
```
|
||||
checkin 240 Night watch duty
|
||||
```
|
||||
Regular check-ins every 4 hours ensure person is alert and safe.
|
||||
|
||||
## Database Schema
|
||||
|
||||
### checkin Table
|
||||
```sql
|
||||
CREATE TABLE checkin (
|
||||
checkin_id INTEGER PRIMARY KEY,
|
||||
checkin_name TEXT,
|
||||
checkin_date TEXT,
|
||||
checkin_time TEXT,
|
||||
location TEXT,
|
||||
checkin_notes TEXT,
|
||||
approved INTEGER DEFAULT 1,
|
||||
expected_checkin_interval INTEGER DEFAULT 0
|
||||
)
|
||||
```
|
||||
|
||||
### checkout Table
|
||||
```sql
|
||||
CREATE TABLE checkout (
|
||||
checkout_id INTEGER PRIMARY KEY,
|
||||
checkout_name TEXT,
|
||||
checkout_date TEXT,
|
||||
checkout_time TEXT,
|
||||
location TEXT,
|
||||
checkout_notes TEXT
|
||||
)
|
||||
```
|
||||
|
||||
## Reverse Mode
|
||||
|
||||
Setting `reverse_in_out = True` in config swaps the meaning of checkin and checkout commands. This is useful if your organization uses opposite terminology.
|
||||
|
||||
With `reverse_in_out = True`:
|
||||
- `checkout` command performs a check-in
|
||||
- `checkin` command performs a check-out
|
||||
|
||||
## Migration from Basic Checklist
|
||||
|
||||
The enhanced checklist is backward compatible with the basic version. Existing check-ins will continue to work, and new features are optional. The database will automatically upgrade to add new columns when first accessed.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Not Seeing Overdue Alerts
|
||||
The overdue detection is built into the module, but alerts need to be configured in the main bot scheduler. Check your scheduler configuration.
|
||||
|
||||
### Wrong Duration Shown
|
||||
Duration is calculated from check-in time to current time. If system clock is wrong, durations will be incorrect. Ensure system time is accurate.
|
||||
|
||||
### Can't Approve/Deny Check-ins
|
||||
These are admin-only commands. Check that your node ID is in the `bbs_admin_list`.
|
||||
|
||||
### Location Not Showing
|
||||
GPS coordinates are only captured if the node has GPS enabled and has a fix. Check node GPS settings.
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Planned features:
|
||||
- Configurable alert thresholds per user
|
||||
- Email/SMS notifications for overdue check-ins
|
||||
- Historical check-in reports
|
||||
- Check-in schedules and recurring events
|
||||
- Geo-fence monitoring
|
||||
- Integration with tracking systems
|
||||
- Mobile app support
|
||||
|
||||
## Support
|
||||
|
||||
For issues or feature requests, please file an issue on the GitHub repository.
|
||||
@@ -0,0 +1,409 @@
|
||||
# Inventory & Point of Sale System
|
||||
|
||||
## Overview
|
||||
|
||||
The inventory module provides a complete point-of-sale (POS) system for mesh networks, enabling inventory management, sales tracking, and cart-based transactions. This system is ideal for:
|
||||
|
||||
- Emergency supply management
|
||||
- Event merchandise sales
|
||||
- Community supply tracking
|
||||
- Remote location inventory
|
||||
- Asset management
|
||||
- Field operations logistics
|
||||
|
||||
## Features
|
||||
|
||||
### 🏪 Complete POS System
|
||||
- **Item Management**: Add, remove, and update inventory items
|
||||
- **Cart System**: Build orders before completing transactions
|
||||
- **Transaction Logging**: Full audit trail of all sales and returns
|
||||
- **Price Tracking**: Track price changes over time
|
||||
- **Location Tracking**: Optional warehouse/location field for items
|
||||
|
||||
### 💰 Financial Features
|
||||
- **Penny Rounding**: USA cash sales support
|
||||
- Cash sales round down to nearest nickel
|
||||
- Taxed sales round up to nearest nickel
|
||||
- **Daily Statistics**: Track sales performance
|
||||
- **Hot Item Detection**: Identify best-selling products
|
||||
- **Revenue Tracking**: Daily sales totals
|
||||
|
||||
### 📊 Reporting
|
||||
- **Inventory Value**: Total inventory worth
|
||||
- **Sales Reports**: Daily transaction summaries
|
||||
- **Best Sellers**: Most popular items
|
||||
|
||||
## Configuration
|
||||
|
||||
Add to your `config.ini`:
|
||||
|
||||
```ini
|
||||
[inventory]
|
||||
enabled = True
|
||||
inventory_db = data/inventory.db
|
||||
# Set to True to enable penny rounding (USA cash sales)
|
||||
# Rounds down for cash sales, up for taxed sales
|
||||
disable_penny = False
|
||||
```
|
||||
|
||||
## Commands Reference
|
||||
|
||||
### Item Management
|
||||
|
||||
#### Add Item
|
||||
```
|
||||
itemadd <name> <price> <quantity> [location]
|
||||
```
|
||||
|
||||
Adds a new item to inventory.
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
itemadd Radio 149.99 5 Shelf-A
|
||||
itemadd Battery 12.50 20 Warehouse
|
||||
itemadd Water 1.00 100
|
||||
```
|
||||
|
||||
#### Remove Item
|
||||
```
|
||||
itemremove <name>
|
||||
```
|
||||
|
||||
Removes an item from inventory (also removes from all carts).
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
itemremove Radio
|
||||
itemremove "First Aid Kit"
|
||||
```
|
||||
|
||||
#### Update Item
|
||||
```
|
||||
itemreset <name> [price=X] [qty=Y]
|
||||
```
|
||||
|
||||
Updates item price and/or quantity.
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
itemreset Radio price=139.99
|
||||
itemreset Battery qty=50
|
||||
itemreset Water price=0.95 qty=200
|
||||
```
|
||||
|
||||
#### Quick Sale
|
||||
```
|
||||
itemsell <name> <quantity> [notes]
|
||||
```
|
||||
|
||||
Sell directly without using cart (for quick transactions).
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
itemsell Battery 2
|
||||
itemsell Water 10 Emergency supply
|
||||
itemsell Radio 1 Field unit sale
|
||||
```
|
||||
|
||||
#### Return Transaction
|
||||
```
|
||||
itemreturn <transaction_id>
|
||||
```
|
||||
|
||||
Reverse a transaction and return items to inventory.
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
itemreturn 123
|
||||
itemreturn 45
|
||||
```
|
||||
|
||||
#### List Inventory
|
||||
```
|
||||
itemlist
|
||||
```
|
||||
|
||||
Shows all items with prices, quantities, and total inventory value.
|
||||
|
||||
**Example Response:**
|
||||
```
|
||||
📦 Inventory:
|
||||
Radio: $149.99 x 5 @ Shelf-A = $749.95
|
||||
Battery: $12.50 x 20 @ Warehouse = $250.00
|
||||
Water: $1.00 x 100 = $100.00
|
||||
|
||||
Total Value: $1,099.95
|
||||
```
|
||||
|
||||
#### Statistics
|
||||
```
|
||||
itemstats
|
||||
```
|
||||
|
||||
Shows today's sales performance.
|
||||
|
||||
**Example Response:**
|
||||
```
|
||||
📊 Today's Stats:
|
||||
Sales: 15
|
||||
Revenue: $423.50
|
||||
Hot Item: Battery (8 sold)
|
||||
```
|
||||
|
||||
### Cart System
|
||||
|
||||
#### Add to Cart
|
||||
```
|
||||
cartadd <name> <quantity>
|
||||
```
|
||||
|
||||
Add items to your shopping cart.
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
cartadd Radio 2
|
||||
cartadd Battery 4
|
||||
cartadd Water 12
|
||||
```
|
||||
|
||||
#### Remove from Cart
|
||||
```
|
||||
cartremove <name>
|
||||
```
|
||||
|
||||
Remove items from cart.
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
cartremove Radio
|
||||
cartremove Battery
|
||||
```
|
||||
|
||||
#### View Cart
|
||||
```
|
||||
cart
|
||||
cartlist
|
||||
```
|
||||
|
||||
Display your current cart contents and total.
|
||||
|
||||
**Example Response:**
|
||||
```
|
||||
🛒 Your Cart:
|
||||
Radio: $149.99 x 2 = $299.98
|
||||
Battery: $12.50 x 4 = $50.00
|
||||
|
||||
Total: $349.98
|
||||
```
|
||||
|
||||
#### Complete Transaction
|
||||
```
|
||||
cartbuy [notes]
|
||||
cartsell [notes]
|
||||
```
|
||||
|
||||
Process the cart as a transaction. Use `cartbuy` for purchases (adds to inventory) or `cartsell` for sales (removes from inventory).
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
cartsell Customer purchase
|
||||
cartbuy Restocking supplies
|
||||
cartsell Event merchandise
|
||||
```
|
||||
|
||||
#### Clear Cart
|
||||
```
|
||||
cartclear
|
||||
```
|
||||
|
||||
Empty your shopping cart without completing a transaction.
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Event Merchandise Sales
|
||||
|
||||
Perfect for festivals, hamfests, or community events:
|
||||
|
||||
```
|
||||
# Setup inventory
|
||||
itemadd Tshirt 20.00 50 Booth-A
|
||||
itemadd Hat 15.00 30 Booth-A
|
||||
itemadd Sticker 5.00 100 Booth-B
|
||||
|
||||
# Customer transaction
|
||||
cartadd Tshirt 2
|
||||
cartadd Hat 1
|
||||
cartsell Festival sale
|
||||
|
||||
# Check daily performance
|
||||
itemstats
|
||||
```
|
||||
|
||||
### 2. Emergency Supply Tracking
|
||||
|
||||
Track supplies during disaster response:
|
||||
|
||||
```
|
||||
# Add emergency supplies
|
||||
itemadd Water 0.00 500 Warehouse-1
|
||||
itemadd MRE 0.00 200 Warehouse-1
|
||||
itemadd Blanket 0.00 100 Warehouse-2
|
||||
|
||||
# Distribute supplies
|
||||
itemsell Water 50 Red Cross distribution
|
||||
itemsell MRE 20 Family shelter
|
||||
|
||||
# Check remaining inventory
|
||||
itemlist
|
||||
```
|
||||
|
||||
### 3. Field Equipment Management
|
||||
|
||||
Manage tools and equipment in remote locations:
|
||||
|
||||
```
|
||||
# Track equipment
|
||||
itemadd Generator 500.00 3 Base-Camp
|
||||
itemadd Radio 200.00 10 Equipment-Room
|
||||
itemadd Battery 15.00 50 Supply-Closet
|
||||
|
||||
# Equipment checkout
|
||||
itemsell Generator 1 Field deployment
|
||||
itemsell Radio 5 Survey team
|
||||
|
||||
# Monitor inventory
|
||||
itemlist
|
||||
itemstats
|
||||
```
|
||||
|
||||
### 4. Community Supply Exchange
|
||||
|
||||
Facilitate supply exchanges within a community:
|
||||
|
||||
```
|
||||
# Add community items
|
||||
itemadd Seeds 2.00 100 Community-Garden
|
||||
itemadd Firewood 10.00 20 Storage-Shed
|
||||
|
||||
# Member transactions
|
||||
cartadd Seeds 5
|
||||
cartadd Firewood 2
|
||||
cartsell Member-123 purchase
|
||||
```
|
||||
|
||||
## Penny Rounding (USA Mode)
|
||||
|
||||
When `disable_penny = True`, the system implements penny rounding:
|
||||
|
||||
### Cash Sales (Round Down)
|
||||
- $10.47 → $10.45
|
||||
- $10.48 → $10.45
|
||||
- $10.49 → $10.45
|
||||
|
||||
### Taxed Sales (Round Up)
|
||||
- $10.47 → $10.50
|
||||
- $10.48 → $10.50
|
||||
- $10.49 → $10.50
|
||||
|
||||
This follows common USA practice where pennies are not used in cash transactions.
|
||||
|
||||
## Database Schema
|
||||
|
||||
The system uses SQLite with four tables:
|
||||
|
||||
### items
|
||||
```sql
|
||||
CREATE TABLE items (
|
||||
item_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
item_name TEXT UNIQUE NOT NULL,
|
||||
item_price REAL NOT NULL,
|
||||
item_quantity INTEGER NOT NULL DEFAULT 0,
|
||||
location TEXT,
|
||||
created_date TEXT,
|
||||
updated_date TEXT
|
||||
)
|
||||
```
|
||||
|
||||
### transactions
|
||||
```sql
|
||||
CREATE TABLE transactions (
|
||||
transaction_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
transaction_type TEXT NOT NULL,
|
||||
transaction_date TEXT NOT NULL,
|
||||
transaction_time TEXT NOT NULL,
|
||||
user_name TEXT,
|
||||
total_amount REAL NOT NULL,
|
||||
notes TEXT
|
||||
)
|
||||
```
|
||||
|
||||
### transaction_items
|
||||
```sql
|
||||
CREATE TABLE transaction_items (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
transaction_id INTEGER NOT NULL,
|
||||
item_id INTEGER NOT NULL,
|
||||
quantity INTEGER NOT NULL,
|
||||
price_at_sale REAL NOT NULL,
|
||||
FOREIGN KEY (transaction_id) REFERENCES transactions(transaction_id),
|
||||
FOREIGN KEY (item_id) REFERENCES items(item_id)
|
||||
)
|
||||
```
|
||||
|
||||
### carts
|
||||
```sql
|
||||
CREATE TABLE carts (
|
||||
cart_id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
user_id TEXT NOT NULL,
|
||||
item_id INTEGER NOT NULL,
|
||||
quantity INTEGER NOT NULL,
|
||||
added_date TEXT,
|
||||
FOREIGN KEY (item_id) REFERENCES items(item_id)
|
||||
)
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Users on the `bbs_ban_list` cannot use inventory commands
|
||||
- Each user has their own cart (identified by node ID)
|
||||
- Transactions are logged with user information for accountability
|
||||
- All database operations use parameterized queries to prevent SQL injection
|
||||
|
||||
## Tips and Best Practices
|
||||
|
||||
1. **Regular Inventory Checks**: Use `itemlist` regularly to monitor stock levels
|
||||
2. **Descriptive Notes**: Add notes to transactions for better tracking
|
||||
3. **Location Tags**: Use consistent location naming for better organization
|
||||
4. **Daily Reviews**: Check `itemstats` at the end of each day
|
||||
5. **Transaction IDs**: Keep track of transaction IDs for potential returns
|
||||
6. **Quantity Updates**: Use `itemreset` to adjust inventory after physical counts
|
||||
7. **Cart Cleanup**: Use `cartclear` if you change your mind before completing a sale
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Item Already Exists
|
||||
If you get "Item already exists" when using `itemadd`, use `itemreset` instead to update the existing item.
|
||||
|
||||
### Insufficient Quantity
|
||||
If you see "Insufficient quantity" error, check available stock with `itemlist` before attempting the sale.
|
||||
|
||||
### Transaction Not Found
|
||||
If `itemreturn` fails, verify the transaction ID exists. Use recent transaction logs to find valid IDs.
|
||||
|
||||
### Cart Not Showing Items
|
||||
Each user has their own cart. Make sure you're using your own node to view your cart.
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Planned features for future releases:
|
||||
- Multi-item itemsell command
|
||||
- Transaction history viewing
|
||||
- Inventory reports by date range
|
||||
- Low stock alerts
|
||||
- Price history tracking
|
||||
- Barcode/QR code support
|
||||
- Integration with external accounting systems
|
||||
|
||||
## Support
|
||||
|
||||
For issues or feature requests, please file an issue on the GitHub repository.
|
||||
Reference in New Issue
Block a user