feat: Add web application interface
Implements a modern web-based interface alongside the existing desktop app. Features: - Flask backend with REST API and WebSocket support - Responsive web UI with TailwindCSS and Alpine.js - Real-time updates via Socket.IO - All desktop features available in browser - Multi-user support - Mobile-friendly responsive design - Same async import queue functionality Technology Stack: - Backend: Flask + Flask-SocketIO + Flask-CORS - Frontend: HTML5 + TailwindCSS + Alpine.js - Real-time: WebSocket (Socket.IO) - Icons: Font Awesome 6 New Files: - src/stocktool/web/app.py - Flask application server - src/stocktool/web/templates/index.html - Main web interface - src/stocktool/web/static/js/app.js - Alpine.js application logic - WEB_APP.md - Complete web app documentation API Endpoints: - GET /api/config - Application configuration - GET /api/locations - List locations - POST /api/part/search - Search for part - POST /api/part/import - Queue part import - POST /api/stock/add - Add stock - POST /api/stock/update - Update stock - POST /api/stock/check - Check stock level - POST /api/part/locate - Locate part - GET /api/pending - Get pending imports WebSocket Events: - import_complete - Part import finished - import_retry - Import failed, retrying - import_failed - Import failed completely - barcode_parsed - Barcode successfully parsed Benefits: - Access from any device with a browser - No desktop installation required - Better mobile experience - Multiple users can work simultaneously - Easier deployment and updates - Network-accessible within local network Usage: uv run stock-tool-web # Open browser to http://localhost:5000 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
254
WEB_APP.md
Normal file
254
WEB_APP.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# InvenTree Stock Tool - Web Application
|
||||
|
||||
A modern web-based interface for InvenTree barcode scanning and inventory management.
|
||||
|
||||
## Features
|
||||
|
||||
- **Modern Web UI**: Responsive design works on desktop, tablet, and mobile
|
||||
- **Real-time Updates**: WebSocket integration for live import progress
|
||||
- **No Installation Required**: Just open in any modern browser
|
||||
- **Multi-User Support**: Multiple users can access simultaneously
|
||||
- **Camera Barcode Scanning**: Use device camera or USB scanner
|
||||
- **Async Part Import**: Non-blocking background imports with visual feedback
|
||||
- **Dark Theme**: Eye-friendly dark interface
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Install Dependencies
|
||||
|
||||
```bash
|
||||
# Make sure web dependencies are installed
|
||||
uv sync
|
||||
```
|
||||
|
||||
### 2. Run the Web Server
|
||||
|
||||
```bash
|
||||
# Using UV (recommended)
|
||||
uv run stock-tool-web
|
||||
|
||||
# Or directly
|
||||
uv run python -m stocktool.web.app
|
||||
```
|
||||
|
||||
### 3. Open in Browser
|
||||
|
||||
Navigate to: **http://localhost:5000**
|
||||
|
||||
The web server will be accessible from any device on your local network at:
|
||||
`http://YOUR_IP_ADDRESS:5000`
|
||||
|
||||
## Usage
|
||||
|
||||
### Location Setup
|
||||
|
||||
1. **Scan Location Barcode**: Enter location barcode (INV-SL format) in the location field
|
||||
2. **Or Select from Dropdown**: Choose from the list of available locations
|
||||
|
||||
### Select Mode
|
||||
|
||||
Click one of the four operation modes:
|
||||
- **Add Stock** - Add new stock or increase quantity
|
||||
- **Update Stock** - Set exact stock quantity
|
||||
- **Check Stock** - View current stock level
|
||||
- **Locate Part** - Find all locations where part is stored
|
||||
|
||||
### Scan Parts
|
||||
|
||||
1. Click in the "Scan Part" field or just start scanning
|
||||
2. Scan barcode or type part code
|
||||
3. Press Enter or click "Process"
|
||||
|
||||
### Pending Imports
|
||||
|
||||
When unknown parts are scanned:
|
||||
- They appear in the "Pending Imports" section
|
||||
- Import runs in background (30s timeout)
|
||||
- You can continue scanning other parts
|
||||
- Part is auto-processed when import completes
|
||||
- Failed imports retry automatically (up to 3 times)
|
||||
|
||||
### Activity Log
|
||||
|
||||
- Shows all operations in real-time
|
||||
- Color-coded messages:
|
||||
- 🔵 Blue: Info
|
||||
- 🟢 Green: Success
|
||||
- 🟡 Yellow: Warning
|
||||
- 🔴 Red: Error
|
||||
|
||||
## Barcode Commands
|
||||
|
||||
Scan special barcodes to control the app:
|
||||
|
||||
**Mode Switching:**
|
||||
- `MODE:ADD`, `IMPORT` → Switch to Add Stock mode
|
||||
- `MODE:UPDATE`, `UPDATE` → Switch to Update Stock mode
|
||||
- `MODE:CHECK`, `CHECK` → Switch to Check Stock mode
|
||||
- `MODE:LOCATE`, `LOCATE` → Switch to Locate Part mode
|
||||
|
||||
**Location:**
|
||||
- `CHANGE_LOCATION`, `LOCATION` → Clear current location
|
||||
|
||||
## Supported Barcode Formats
|
||||
|
||||
1. **JSON-like**: `{PM:PART-CODE,QTY:10}`
|
||||
2. **Separator-based**: Uses GS/RS separators (`\x1D`, `\x1E`)
|
||||
3. **InvenTree locations**: `INV-SL<location_id>`
|
||||
|
||||
## API Endpoints
|
||||
|
||||
The web app exposes a RESTful API:
|
||||
|
||||
### Configuration
|
||||
- `GET /api/config` - Get app configuration
|
||||
|
||||
### Locations
|
||||
- `GET /api/locations` - List all locations
|
||||
|
||||
### Parts
|
||||
- `POST /api/part/search` - Search for a part
|
||||
- `POST /api/part/import` - Queue part for import
|
||||
- `POST /api/part/locate` - Find part locations
|
||||
|
||||
### Stock Operations
|
||||
- `POST /api/stock/add` - Add stock
|
||||
- `POST /api/stock/update` - Update stock quantity
|
||||
- `POST /api/stock/check` - Check stock level
|
||||
|
||||
### Pending Imports
|
||||
- `GET /api/pending` - Get pending imports list
|
||||
|
||||
## WebSocket Events
|
||||
|
||||
Real-time events via Socket.IO:
|
||||
|
||||
**Server → Client:**
|
||||
- `connected` - Connection established
|
||||
- `barcode_parsed` - Barcode successfully parsed
|
||||
- `import_complete` - Part import finished successfully
|
||||
- `import_retry` - Import failed, retrying
|
||||
- `import_failed` - Import failed after all retries
|
||||
|
||||
**Client → Server:**
|
||||
- `parse_barcode` - Parse a barcode string
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- **Backend**: Flask + Flask-SocketIO
|
||||
- **Frontend**: HTML5 + TailwindCSS + Alpine.js
|
||||
- **Real-time**: WebSocket (Socket.IO)
|
||||
- **Icons**: Font Awesome 6
|
||||
- **Barcode**: Keyboard input (camera support coming soon)
|
||||
|
||||
## Configuration
|
||||
|
||||
Uses the same configuration file as the desktop app:
|
||||
|
||||
**Location**: `~/.config/scan_and_import.yaml`
|
||||
|
||||
```yaml
|
||||
host: https://your-inventree-server.com
|
||||
token: your-api-token-here
|
||||
```
|
||||
|
||||
## Network Access
|
||||
|
||||
### Local Network Access
|
||||
|
||||
To access from other devices on your network:
|
||||
|
||||
1. Find your computer's IP address:
|
||||
```bash
|
||||
# Windows
|
||||
ipconfig
|
||||
|
||||
# Linux/Mac
|
||||
ifconfig
|
||||
```
|
||||
|
||||
2. Open browser on any device:
|
||||
```
|
||||
http://YOUR_IP_ADDRESS:5000
|
||||
```
|
||||
|
||||
### Production Deployment
|
||||
|
||||
For production use, consider:
|
||||
|
||||
1. **Reverse Proxy**: Use nginx or Apache
|
||||
2. **HTTPS**: Enable SSL/TLS for security
|
||||
3. **Process Manager**: Use systemd or supervisor
|
||||
4. **Firewall**: Configure appropriate access rules
|
||||
|
||||
Example nginx config:
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name stock-tool.local;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:5000;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_set_header Host $host;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
Change the port in `app.py`:
|
||||
```python
|
||||
socketio.run(app, host='0.0.0.0', port=5001, ...)
|
||||
```
|
||||
|
||||
### WebSocket Connection Failed
|
||||
|
||||
Check your firewall settings allow port 5000.
|
||||
|
||||
### Slow Import Performance
|
||||
|
||||
The import uses `inventree-part-import` which can be slow. This is normal.
|
||||
The web UI stays responsive while imports run in background.
|
||||
|
||||
## Comparison: Web vs Desktop
|
||||
|
||||
| Feature | Web App | Desktop App |
|
||||
|---------|---------|-------------|
|
||||
| Installation | None (browser only) | Python + dependencies |
|
||||
| Platform | Any (browser) | Windows/Linux/Mac |
|
||||
| Multi-user | Yes | No |
|
||||
| Mobile friendly | Yes | No |
|
||||
| Camera scanning | Coming soon | No |
|
||||
| Async imports | Yes | Yes |
|
||||
| Real-time updates | WebSocket | UI updates |
|
||||
| Deployment | Server-based | Local install |
|
||||
|
||||
## Development
|
||||
|
||||
### Run in Debug Mode
|
||||
|
||||
```bash
|
||||
# Flask debug mode is enabled by default
|
||||
uv run stock-tool-web
|
||||
```
|
||||
|
||||
### Customize UI
|
||||
|
||||
Edit files in:
|
||||
- `src/stocktool/web/templates/` - HTML templates
|
||||
- `src/stocktool/web/static/js/` - JavaScript
|
||||
- `src/stocktool/web/static/css/` - CSS (uses Tailwind CDN)
|
||||
|
||||
### Add New Endpoints
|
||||
|
||||
Edit `src/stocktool/web/app.py` and add route handlers.
|
||||
|
||||
## License
|
||||
|
||||
MIT License - Same as the main project
|
||||
Reference in New Issue
Block a user