# 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.

---

## 📱 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).
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

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

---

## 🔍 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.
1. Tap the **Package (Box)** icon in the header to open the **Box Inventory**.
2. Find the box you want to label and tap **Print Label**.
3. **Desktop:** Use the print dialog to send the label directly to a Dymo/Brother thermal printer.
4. **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:
- **`config/`**: Contains all network settings (`network_config.env`), LDAP profiles (`ldap_config.json`), and security proxy rules (`Caddyfile`).
- **Dynamic Port Mapping**: Changes to the server IP or ports in the configuration 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.

---

## 📞 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.8.0
**Last Updated:** 2026-04-13
