inventree-stock-tool/README.md

# InvenTree Stock Tool

A comprehensive barcode scanning application for InvenTree inventory management with a modern GUI.

![Python](https://img.shields.io/badge/python-3.8+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

## Features

- **Barcode Scanning**: Process barcodes in multiple formats (JSON-like, separator-based)
- **Multiple Operation Modes**:
  - Add Stock: Create new stock items or add to existing ones
  - Update Stock: Manually update stock quantities
  - Check Stock: View current stock levels
  - Locate Part: Find all locations where a part is stored
- **Smart Duplicate Prevention**: Automatically adds to existing stock items instead of creating duplicates
- **Real-time Server Monitoring**: Visual connection status indicator
- **Part Information Display**: Shows part details, parameters, and images
- **Debug Mode**: Optional detailed logging for troubleshooting

## Screenshots

The application features a dark-themed interface with:
- Location scanner
- Mode selection (Add/Update/Check/Locate)
- Part information display with images
- Real-time activity logging
- Server connection status

## Requirements

- Python 3.8 or higher
- InvenTree server instance
- Required Python packages:
  - `sv-ttk` - Modern themed tkinter widgets
  - `pillow` - Image handling
  - `requests` - HTTP API communication
  - `pyyaml` - Configuration file parsing

## Installation

1. Clone this repository:
```bash
git clone <your-gitea-url>/stocktool.git
cd stocktool
```

2. Install dependencies:
```bash
pip install sv-ttk pillow requests pyyaml
```

3. Create configuration file at `~/.config/scan_and_import.yaml`:
```yaml
host: https://your-inventree-server.com
token: your-api-token-here
```

## Configuration

### Config File Location
- **Linux/Mac**: `~/.config/scan_and_import.yaml`
- **Windows**: `C:\Users\<username>\.config\scan_and_import.yaml`

### Config File Format
```yaml
host: https://inventree.example.com  # Your InvenTree server URL (no trailing slash)
token: abcdef1234567890                # Your InvenTree API token
```

### Getting Your API Token
1. Log into your InvenTree instance
2. Navigate to Settings > User Settings > API Tokens
3. Create a new token or copy an existing one

## Usage

### Starting the Application
```bash
python stock_tool_gui_v2.py
```

### Basic Workflow

1. **Set Location**: Scan a location barcode (format: `INV-SL<location_id>`)
2. **Select Mode**: Choose operation mode (Add/Update/Check/Locate)
3. **Scan Parts**: Scan part barcodes to perform operations

### Supported Barcode Formats

#### JSON-like Format
```
{pbn:PICK251017100019,on:WM2510170196,pc:C18548292,pm:STHW4-DU-HS24041,qty:150,mc:,cc:1,pdi:180368458,hp:null,wc:JS}
```
- `pm`: Part code
- `qty`: Quantity

#### Separator-based Format
Uses ASCII separators (GS/RS) to delimit fields:
- `30P<part_code>` - Part code with 30P prefix
- `1P<part_code>` - Part code with 1P prefix
- `Q<quantity>` - Quantity

### Barcode Commands

You can use special barcodes to control the application:

**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

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

**Location Management:**
- `CHANGE_LOCATION` - Prompt for new location

## Operation Modes

### Add Stock Mode
Adds stock to InvenTree. If the part already exists at the location, it adds to the existing stock item instead of creating a duplicate.

**Example:**
- First scan: Creates StockItem #123 with quantity 150
- Second scan: Updates StockItem #123 to quantity 250 (adds 100)

### Update Stock Mode
Manually set the stock quantity for a part. Opens a dialog to enter the exact quantity.

### Check Stock Mode
Displays the current stock level for a part at the selected location.

### Locate Part Mode
Shows all locations where a part is stored, with quantities at each location.

## Character Encoding

The tool automatically cleans non-ASCII characters from part codes, handling common barcode encoding issues:
- Input: `STHW4-DU-HS24041¡­`
- Cleaned: `STHW4-DU-HS24041`

## API Compatibility

This tool works with InvenTree's REST API and handles various response formats:
- Paginated responses with `results` key
- Direct list responses
- Single object responses

## Troubleshooting

### Connection Issues
- Check that your InvenTree server URL is correct
- Verify your API token is valid
- Ensure the server is accessible from your network
- Check the connection status indicator (green = connected)

### Import Failures
If a part cannot be found, the tool attempts to import it using `inventree-part-import`. Ensure this tool is installed and configured.

### Debug Mode
Enable debug mode via checkbox or `DEBUG:ON` barcode to see detailed operation logs.

## Recent Fixes

### Version 2.x (Latest)
- Fixed encoding issues with non-ASCII characters in part codes
- Fixed API response handling for both list and dict formats
- Implemented smart duplicate prevention when adding stock
- Moved misplaced function definitions to correct locations
- Added comprehensive error logging with tracebacks

See `FIXES_APPLIED.md` for detailed information about recent bug fixes.

## Development

### Project Structure
```
stocktool/
├── stock_tool_gui_v2.py          # Main application
├── FIXES_APPLIED.md              # Documentation of bug fixes
├── test_parse_fix.py             # Test for encoding fixes
├── test_stock_level.py           # Test for stock level retrieval
├── test_add_stock.py             # Test for API response handling
├── test_duplicate_handling.py    # Test for duplicate prevention
├── .gitignore                    # Git ignore rules
└── README.md                     # This file
```

### Running Tests
```bash
python test_parse_fix.py
python test_stock_level.py
python test_add_stock.py
python test_duplicate_handling.py
```

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For issues, questions, or contributions, please use the repository's issue tracker.

## Acknowledgments

- Built for use with [InvenTree](https://inventree.org/)
- Uses [sv-ttk](https://github.com/rdbende/Sun-Valley-ttk-theme) for modern theming