bede/tfm_ainventory
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

chore: major codebase cleanup and documentation consolidation

Browse Source
This commit is contained in:
Daniel Bedeleanu
2026-04-23 11:44:33 +03:00
parent 0e356e6c89
commit 8aeabcf1f5
72 changed files with 380 additions and 28893 deletions
Download Patch File Download Diff File Expand all files Collapse all files

176
USER_GUIDE.md
View File

@@ -1,154 +1,46 @@
# TFM aInventory - User Guide
Welcome to **TFM aInventory**, the unified inventory management system. This guide explains how to use the application for managing your inventory.
Welcome to **TFM aInventory**, the unified inventory management system.
---
## 📱 Installing on Mobile (PWA)
The application is a **Progressive Web App**, which means you don't need to download it from the App Store or Google Play.
1. Open the application URL in your browser (e.g., Safari on iOS or Chrome on Android).
2. Tap the **Share** button (iOS) or the **three dots menu** (Android).
1. Open the application URL in your mobile browser (Safari for iOS, Chrome for Android).
2. Tap the **Share** button (iOS) or the **Menu** dots (Android).
3. Select **"Add to Home Screen"**.
4. The application will now appear as an icon on your home screen and run in immersive mode (without browser chrome).
---
## 🔐 Authentication
- **LDAP/Enterprise Login**: Use your company account. The app securely caches credentials for offline use.
- **Local Login**: Standard username/password provided by your admin.
- **Offline Access**: You can log in even without signal if you have logged in on that device at least once before.
- **Default User:** On first installation, use `Admin` / `<initial-password>` (check your system administrator for the initial password).
- **Change Password:** We recommend changing your password immediately from the Admin settings.
- **LDAP/Enterprise Login:** If your administrator has configured LDAP integration, you can log in with your company/domain account. The application will securely cache a **cryptographic hash** of your credentials (using PBKDF2) to allow offline access (e.g., in areas without signal like basements). **Note: Your actual password is NEVER stored in plain text on the local device.**
- **JWT Tokens:** Your login session is secured with JWT bearer tokens that expire after 8 hours. You will be automatically logged out when your token expires.
## 🔍 Core Workflows
### Adding Items (AI Wizard)
1. Tap the **Camera/Plus** button.
2. Capture a photo of the item's label.
3. The AI will automatically extract Name, PN, and Category.
4. Review, adjust the quantity, and **Save**.
### Scanning Barcodes
1. Open the **Scanner** tab.
2. Point the camera at a barcode or QR code.
3. If the item exists, its details will appear instantly for stock adjustment.
### Stock Adjustment
- Use the **+/-** buttons for quick changes.
- Tap the quantity number to type a specific value.
## ☁️ Offline Sync
- Work anywhere, including basements or remote sites.
- Changes are saved locally and synced automatically when signal returns.
- Check the **Sync** status in the Bottom Navigation bar.
## 🛠 Admin Tasks
Administrators can access the **Admin Overlay** to:
- Manage Users and Categories.
- Configure AI Providers (Gemini/Claude).
- Perform Database Backups and Restore.
- View detailed Audit Logs of all actions.
---
## 🔍 Scanning and Adding Items
The application supports two scanning modes:
### Manual / Barcode Scanning
Scan an existing barcode to locate or update an item in your inventory.
If no readable text is found, the scanner silently retries on the next cycle.
### Box & Container Scanning (NEW v1.6.0)
You can now manage containers more efficiently with two specialized methods:
- **AI Box Discovery**: When adding a new container through **AI Discovery**, use the **"Box / Container"** toggle. Gemini will focus exclusively on the container's name, ignoring technical noise on labels.
- **Targeted Field Scanning**: In the **Edit Item** modal, tap the small **Camera icon** next to the "Box / Container Label" field. The scanner will capture the next physical label directly into the text field.
- **Automatic Matching**: In the main scanner, scanning a box identifies all its contents. Scanning a box and then an item will suggest linking them together if they aren't already matched.
---
## 🏷️ Label Printing
Administrators and users can generate physical labels for boxes to ensure 100% accurate scanning.
## 🏷️ Label Printing
Administrators and users can generate physical labels for boxes to ensure 100% accurate scanning.
1. Tap the **Package (Box)** icon in the global header or the **Manage Boxes** card on the dashboard to open the **Box Inventory**.
2. **Search:** Use the search bar inside the Box Manager to filter through your containers in real-time.
3. Find the box you want to label and tap **Print Label**.
4. **Desktop:** Use the print dialog to send the label directly to a Dymo/Brother thermal printer.
5. **Mobile:** Use **"Save for Mobile App"** to download a PNG image of the label, which you can then print using your Bluetooth printer's app (like NIIMBOT).
---
## 📂 Inventory Organization
The inventory is organized in a hierarchical structure:
- **Categories:** Broad groupings (e.g., Connectors, Spare Parts, Tools, Consumables).
- **Items:** Individual products within categories, identified by barcode.
- **Item Properties:** Name, part number, color, technical specifications, and quantity.
---
## 📶 Offline Operation
The application is designed to work even when you don't have internet connectivity in your warehouse or field location:
- **Offline Data:** All item data, categories, and your pending operations are stored locally on your device using IndexedDB.
- **Automatic Sync:** When you return to an area with internet connectivity, pending check-ins, check-outs, and other operations are automatically synchronized with the server.
- **UUID Tracking:** Each offline operation is tagged with a unique ID to prevent duplicates during synchronization.
---
## 📜 Activity Log (Audit Trail)
All actions (additions, modifications, deletions) are recorded in real-time with your user ID and timestamp. You can review the activity history in the **Logs** section to see:
- Who performed the action
- What action was performed (Check-in, Check-out, Item creation, etc.)
- When the action occurred
- The item affected and quantity changed
---
## ⚙️ Admin Functions
### User Management
Administrators can:
- View all system users
- Create new users (local or LDAP-integrated)
- Modify user roles (admin or standard user)
- Delete users (except the default Admin account)
### LDAP Configuration
If your organization uses LDAP/Active Directory, administrators can:
- Configure LDAP server connection details
- Set up role mapping (group membership → admin/user roles)
- Test LDAP connectivity
### Settings
Access application settings from the **Admin** panel.
### 🌐 Network & Configuration (NEW v1.8.0)
The application now uses a centralized configuration folder in the project root:
- **`inventory.env`**: The primary network configuration file. Centralizes `SERVER_IP`, ports, and `EXTRA_ALLOWED_ORIGINS`.
- **Dynamic Port Mapping**: Changes to the server IP, ports, or allowed origins are automatically detected by both the frontend and backend after a restart.
---
## 🚨 Security Notices
- **Do not share your login credentials** with other users. Each user should have their own account.
- **Logout when done:** Always log out when finished to protect your account.
- **Report suspicious activity:** If you notice unauthorized changes in the audit log, contact your system administrator immediately.
- **API Security:** The application uses JWT (JSON Web Tokens) for API authentication. Tokens are valid for 8 hours.
---
## ❓ Troubleshooting
### "Insufficient Stock" Error
You attempted to check out more items than are currently in inventory. Check the current stock level and try again with a valid quantity.
### Offline Mode Not Syncing
Ensure you have internet connectivity and wait a moment. Synchronization happens automatically when the connection is re-established. You can manually refresh the page to trigger an immediate sync.
### Login Failed
- Verify your username and password are correct.
- If using LDAP, ensure your domain credentials are correct and the server is reachable.
- Check with your system administrator if you cannot reset your password.
### AI Label Extraction Not Working
- Ensure adequate lighting when photographing the label.
- The label image must be clear and not blurry.
- The image size must not exceed 10 MB.
- The application supports JPEG, PNG, WebP, and GIF formats.
- If the AI service is unavailable, try again later or contact your administrator.
- **AI Provider Toggle:** In the Admin Dashboard, you can choose between **Gemini** and **Claude** for label extraction. If one provider is slow or failing, your administrator can switch to the other seamlessly.
---
## 📞 Technical Support
For technical assistance, contact your system administrator or email: `support@example.com`
For detailed technical documentation, see the [Project Architecture](../PROJECT_ARCHITECTURE.md) guide.
---
**Version:** v1.9.24
**Last Updated:** 2026-04-15
*Refer to DEPLOYMENT.md for server setup instructions.*