inventree-stock-tool/README.md

# InvenTree Stock Tool

A comprehensive barcode scanning application for InvenTree inventory management.

**Available in two versions:**
- **Desktop App** (tkinter) - Traditional GUI application
- **Web App** (Flask) - Modern browser-based interface **⭐ NEW!**

## Features

- **Stock Addition**: Add stock to inventory by scanning barcodes
- **Stock Updates**: Update existing stock levels
- **Stock Checking**: Check current stock levels
- **Part Location**: Find where parts are stored
- **Async Part Import**: Non-blocking background import for unknown parts
- **Server Connection Monitoring**: Real-time connection status
- **Barcode Command Support**: Control the app via barcode commands
- **Web Interface**: Access from any device with a browser (NEW!)

## Requirements

- Python 3.9 or higher
- InvenTree server with API access

## Installation

### Using UV (Recommended)

```bash
# Clone the repository
git clone <repository-url>
cd stocktool

# Install with uv
uv sync

# Run the DESKTOP application
uv run stock-tool

# OR run the WEB application
uv run stock-tool-web
# Then open browser to http://localhost:5000
```

**👉 For Web App setup, see [WEB_APP.md](WEB_APP.md)**

### Manual Installation

```bash
# Install dependencies
pip install sv-ttk pillow requests pyyaml

# Run the application
python src/stocktool/stock_tool_gui_v2.py
```

## Configuration

Create a configuration file at `~/.config/scan_and_import.yaml`:

```yaml
host: https://your-inventree-server.com
token: your-api-token-here
```

### Required Fields
- `host`: Your InvenTree server URL (without trailing slash)
- `token`: Your InvenTree API token

## Usage

1. **Select Location**: Scan a location barcode or enter location ID
2. **Select Mode**: Choose operation mode (Add Stock, Update Stock, Check Stock, or Locate Part)
3. **Scan Parts**: Scan part barcodes to perform operations

### Async Part Import (New!)

When you scan a part that doesn't exist in the system:

1. **Part is automatically queued** for background import
2. **Continue scanning other parts** - no waiting required!
3. **Watch the "Pending Imports" section** to see import progress
4. **Part is automatically processed** when import completes
5. **Failed imports retry automatically** (up to 3 attempts)

**Benefits**:
- No more UI freezing when importing parts
- Scan multiple unknown parts in quick succession
- Visual feedback showing import progress
- Automatic error handling and retry logic

### Barcode Commands

The application supports special barcode commands for quick mode switching:

- **Mode Switching**:
  - `MODE:ADD`, `MODE:IMPORT`, `ADD_STOCK`, `IMPORT` - Switch to Add Stock mode
  - `MODE:UPDATE`, `UPDATE_STOCK`, `UPDATE` - Switch to Update Stock mode
  - `MODE:CHECK`, `MODE:GET`, `CHECK_STOCK`, `CHECK` - Switch to Check Stock mode
  - `MODE:LOCATE`, `LOCATE_PART`, `LOCATE`, `FIND_PART` - Switch to Locate Part mode

- **Debug Control**:
  - `DEBUG:ON`, `DEBUG_ON` - Enable debug mode
  - `DEBUG:OFF`, `DEBUG_OFF` - Disable debug mode

- **Location Management**:
  - `CHANGE_LOCATION`, `NEW_LOCATION`, `SET_LOCATION`, `LOCATION` - Change current location

### Supported Barcode Formats

The application supports multiple barcode formats:

1. **JSON-like format**: `{PM:PART-CODE,QTY:10}`
2. **Separator-based format**: Fields separated by `\x1D` or `\x1E`
   - Part codes starting with `30P` or `1P`
   - Quantities starting with `Q`
3. **InvenTree location barcodes**: `INV-SL<location_id>`

## Development

### Project Structure

```
stocktool/
├── src/
│   └── stocktool/
│       ├── __init__.py
│       └── stock_tool_gui_v2.py
├── tests/
│   ├── __init__.py
│   ├── test_add_stock.py
│   ├── test_duplicate_handling.py
│   ├── test_parse_fix.py
│   └── test_stock_level.py
├── pyproject.toml
├── .gitignore
└── README.md
```

### Running Tests

```bash
# Using UV
uv run pytest

# Manual
pytest tests/
```

### Building

```bash
# Build the package
uv build

# Install locally
uv pip install -e .
```

## License

MIT License

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.