Initial commit: InvenTree Stock Tool v2
A comprehensive barcode scanning application for InvenTree inventory management. Features: - Multi-mode operation (Add/Update/Check/Locate stock) - Smart duplicate prevention when adding stock - Barcode scanning with automatic part code cleaning - Real-time server connection monitoring - Part information display with images - Debug mode for troubleshooting Fixes applied: - Fixed encoding issues with non-ASCII characters in barcodes - Fixed API response handling for list and dict formats - Implemented duplicate prevention using PATCH to update existing stock - Added comprehensive error handling and logging Includes test suite for verification of all fixes.
This commit is contained in:
219
README.md
Normal file
219
README.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# InvenTree Stock Tool
|
||||
|
||||
A comprehensive barcode scanning application for InvenTree inventory management with a modern GUI.
|
||||
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
Reference in New Issue
Block a user