diff --git a/AI_RULES.md b/AI_RULES.md index b8d2a50e..28f74c9c 100644 --- a/AI_RULES.md +++ b/AI_RULES.md @@ -1,44 +1,42 @@ -# AI AGENT RULES - SINGLE SOURCE OF TRUTH +# AI AGENT RULES - MANDATORY ENTRY POINT -This file is the single source of truth for ALL Artificial Intelligence agents working on this project (Claude, Gemini, etc.). -Agent-specific instructions are located in `GEMINI.md` and `CLAUDE.md`. -Any AI or session MUST respect these mandatory rules. +**READ THIS ENTIRE FILE BEFORE EXECUTING ANY TASK.** +This is the **Single Source of Truth** for ALL Artificial Intelligence agents (Claude, Gemini, etc.) working on this project. +For technical architecture, data models, and stack details, refer to [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md). -## General Rules -- **UI & Code Language**: All web interfaces, functions, variables, and any text inside the application MUST BE DIRECTLY AND ONLY IN ENGLISH. -- **Communication Language**: Conversation with the user will be in Romanian or English, preferably Romanian. - -## Multi-AI Coordination & Handover +## 1. Multi-AI Coordination & Memory - **MANDATORY STARTUP**: Every AI session MUST first read `dev_docs/SESSION_STATE.md` to understand current context. -- **MANDATORY HANDOVER**: At the end of every task/session, create or update a handover note in `dev_docs/SESSION_STATE.md`. Specify: **Active AI**, **Current Status**, **Technical Context** (details not in code), and **Next Steps**. -- **ARCHIVAL RULE**: To prevent `SESSION_STATE.md` from bloating, incoming AI agents MUST move all content of the *previous* session handover into the top of `dev_docs/SESSION_HISTORY.md` before writing their own new state. This keeps `SESSION_STATE.md` focused only on the *active* session. -- **NO INTERACTION OVERLAP**: Never modify a file if another AI session is explicitly working on it according to `SESSION_STATE.md`. +- **MANDATORY HANDOVER**: At the end of every task/session, update the handover note in `dev_docs/SESSION_STATE.md`. Specify: **Active AI**, **Current Status**, **Technical Context**, and **Next Steps**. +- **ARCHIVAL RULE**: Before writing new state, move all content of the *previous* session handover into the top of `dev_docs/SESSION_HISTORY.md` to prevent bloat. +- **NO INTERACTION OVERLAP**: Never modify a file if another AI session is explicitly working on it. -## Implementation Completion -- All code modifications MUST be committed in git before the task is considered finished. `VERSION.json` must be updated on EACH commit. -- **MANDATORY GIT RULE:** Never push to remote unless explicitly requested by the user. Only commit locally with proper messages. Always assume the user will handle all `git push` operations. If a task requires pushing, ask for explicit permission first. -- **GIT BINARY PATH**: On this macOS environment, the system `git` (in `/usr/bin/git`) is often broken due to `xcode-select` issues. ALWAYS use the binary path stored in `.git_path` at the project root for all Git operations. -- **GIT BRANCHING STRUCTURE**: - - The main stable branch is `master`. - - All active development MUST occur in the `dev` branch. - - Every major version MUST have its own dedicated archival branch named `vX` (e.g., `v1`, `v2`) which copies the state of the major release. -- **MANDATORY GIT RULE**: NO AI is allowed to write in git commits that it is the author or co-author (e.g., DO NOT add texts like `Co-Authored-By: AI...`). Commits should only contain technical messages. -- **MANDATORY LOGGING**: Any modification of code, architecture, or logic MUST be documented in `dev_docs/ARCHIVE_LOGS.md` at the end of the task. The log must include modified files, purpose of modification, and (if applicable) test results. -- **MANDATORY PLAN ARCHIVING**: Once a phase or task is confirmed as completed and verified, the Architect (Gemini/AI) MUST move these entries from `PLAN.md` into `dev_docs/PLAN_HISTORY.md`. This maintains the active plan's focus and prevents document bloat. -- After finishing an entire job, end your final response on a separate line exactly with: +## 2. Global Operational Laws +- **STRICT ENGLISH POLICY**: All web interfaces, code, variables, scripts, and documentation MUST BE DIRECTLY AND ONLY IN ENGLISH. If you find Romanian text in code, translate it immediately. +- **COMMUNICATION LANGUAGE**: Conversation with the user will be in Romanian or English (preferably Romanian). +- **GIT BINARY PATH**: On this macOS environment, the system `git` is often broken. ALWAYS use the binary path stored in `.git_path` at the project root for all Git operations. +- **COMMIT & PUSH STRICT RULE**: + - Never push to remote (`git push`) or use force flags (`--hard`, `--force`) unless explicitly requested. + - Always update `VERSION.json` on every commit. + - Do NOT add AI co-author signatures (e.g., `Co-Authored-By: AI...`) to commit messages. + - Branching: `master` (stable), `dev` (active development), `vX` (archival releases). +- **MANDATORY LOGGING**: Document coding/architecture changes in `dev_docs/ARCHIVE_LOGS.md` at the end of the task. +- **TRIPLE CONFIRMATION (Safe Forget)**: You cannot delete a physical location, item, or critical entity without explicit user permission three times. + +## 3. UI/UX Fidelity Specifications +- **Fidelity First**: Never simplify the UI unless asked. Density and aesthetics must remain "Premium". +- **Styling**: Tailwind CSS. Font weights/spacing must be consistent (Inter/Roboto). +- **Readability**: NO `uppercase` or `tracking-widest` styles. Use standard camel/Title case. +- **Icons**: Use **Lucide Icons** exclusively. NO emojis. +- **Interactive Affordance**: All select/dropdown boxes MUST have a `ChevronDown` icon. Masked passwords should have reduced opacity (`text-white/50`). +- **Iconography Standardization**: + - **Categories**: ALWAYS use `Layers` (Color: `text-primary`). + - **Item Types**: ALWAYS use `Package` (Color: `text-green-500`). + +## 4. End of Session Protocol +- Once a phase/task from `PLAN.md` is completed and verified, move that entry into `dev_docs/PLAN_HISTORY.md`. +- After finishing an entire job (including updating session state, architecture logs, and versioning), end your final response on a separate line exactly with: ``` --- ✓ Done. ``` -- Do not provide unnecessary summaries of the code. - -## Triple Confirmation & Safety Limits -- **Safe Forget**: You cannot delete a physical location, item, or critical entity without a triple confirmation mechanism. -- **No Force Operations**: Never use destructive flags (e.g., `git reset --hard`, `git push --force`, `rm -rf`) without explicit user permission. - -## UI/UX & Documentation Rules -- **STRICT ENGLISH POLICY**: ANY TEXT within the application (documentation, scripts, CLI, UI, internal comments, logs, etc.) MUST be strictly in English. NO Romanian characters (ăâîșț) or words are allowed in the repository. -- **MANDATORY TRANSLATION**: Any Romanian text found during an AI session (in any file) MUST be translated to English immediately. -- Use Lucide Icons (standard React components); never use emojis or legacy Bootstrap icons. -- The UI must remain fully functional offline (no external CDNs). -- **MANDATORY UI FIDELITY**: Any modification to UI components (headers, banners, cards, buttons) MUST comply with the specifications in `dev_docs/UI_FIDELITY_SPEC.md` to prevent regressions. All agents MUST read that document before modifying frontend code. +- Do not provide unnecessary verbatim summaries of the code. diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index 0f229801..00000000 --- a/GEMINI.md +++ /dev/null @@ -1,29 +0,0 @@ -# GEMINI AGENT CONTEXT (Memory & Rules) - -This file is the specific entry point for **Gemini** (Antigravity). It summarizes critical project knowledge and operational rules to ensure continuity and high-fidelity output. - -## 🚀 Quick Access -- **Primary Rules:** [AI_RULES.md](AI_RULES.md) -- **Technical Stack:** Section 2 in [requirements.md](requirements.md) -- **Active Plan:** [PLAN.md](PLAN.md) -- **Session State:** [dev_docs/SESSION_STATE.md](dev_docs/SESSION_STATE.md) -- **UI Specs:** [dev_docs/UI_FIDELITY_SPEC.md](dev_docs/UI_FIDELITY_SPEC.md) - -## 🏗 Operations & Tooling -- **Git Binary:** Path is in `.git_path` (Relative to project root). -- **Versioning:** Always update `VERSION.json` on every commit. -- **Logbook:** Update `dev_docs/ARCHIVE_LOGS.md` after every feature/fix. -- **Dev Servers:** Frontend (Port 3000), Backend (Port 8000 via `./start_server.sh`). - -## 🧠 Project Specific Knowledge -- **Iconography System:** - - **Categories:** Always use `Layers` (Primary color: `text-primary`). - - **Item Types:** Always use `Package` (Color: `text-green-500`). - - **Indicators:** Use `ChevronDown` for selects/interactive dropdowns. -- **Offline Protocol:** Users can log in while offline if they have authenticated via LDAP at least once before (hash is cached locally). -- **Naming Policy:** Application text MUST be English. User conversation is Romanian. - -## 📜 Personal Directives -1. **Fidelity First:** Never simplify UI unless explicitly asked. Density and aesthetics must remain "Premium". -2. **Case Sensitivity:** Backend searches (SQLite) are often case-sensitive; front-end should normalize to UPPERCASE for barcodes/PNs. -3. **Commit Messages:** Use conventional commits (`feat:`, `fix:`, `style:`, etc.). diff --git a/PLAN.md b/PLAN.md index 0b8ee28c..2a95fc0e 100644 --- a/PLAN.md +++ b/PLAN.md @@ -1,44 +1,13 @@ -# Inventory PWA System Architecture & Implementation Plan +# Active Development Plan -This document defines the technical architecture and rules for the InventoryAI System (2026 Edition). - -## 1. Core Architecture -See the detailed [dev_docs/TECH_STACK.md](dev_docs/TECH_STACK.md) for official framework, database, and library versions. -Summary: FastAPI / Python 3.12+ (Backend) & Next.js 15+ PWA (Frontend). Sync via Dexie.js (client side) and SQL sync logic (v1.2.4). - -## 2. AI Intelligence Strategy (Critical) - -### 2.1 AI Usage Policy -- **New Item Onboarding:** AI-OCR is permitted. It analyzes complex label photos (SFP, hardware specs) and maps them to JSON fields. -- **Routine Operations (Check-in/Out/Audit):** **AI IS STRICTLY FORBIDDEN.** - - Use local barcode/QR scanning only. - - If a label is not recognized locally, the user is prompted to start the "AI Onboarding Assistant". - - Goal: $0 cost for 99% of daily operations. - -### 2.2 Modular AI Providers Architecture -Located in `backend/ai/`, the system supports multiple providers through a managed orchestrator: -- **Provider Modules:** `gemini.py`, `claude.py`, etc. -- **SDK Update (v2):** Switched to `google-genai` (v2) for improved stability and response parsing. -- **Model Hardcoding Power:** Switched from dynamic discovery to fixed high-speed models (`gemini-2.0-flash`) for sub-second responses on cellular networks. - -### 2.3 Hybrid Sync & Deduplication (New) -To ensure zero data loss during unstable mobile sessions: -- **UUID Labeling:** Every sync operation generated on a mobile device is tagged with a client-side UUID. -- **Idempotent Backend:** The `bulk_sync` endpoint checks UUIDs against `AuditLog` before applying increments, preventing double-counts. - -## 3. Data Integrity & Audit -- **Immutable Audit Log:** Every change (Add, Remove, Edit) is logged with a timestamp, action, and previous/new state. -- **Validation Mask:** AI-extracted data is NEVER saved directly. It is presented to a human user in a validation UI for final confirmation. - -## 4. Implementation Status +This document tracks the immediate implementation checklist. For overarching design and constraints, see [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md). +## Implementation Status - [x] **Phase 1: Backend Foundation** (FastAPI, SQLite, Models). -- [x] **Phase 2: Modular AI Integration** (Gemini & Claude support, v2 SDK). -- [x] **Phase 3: AI Onboarding UI** (Validation Mask, Camera/Upload integration). +- [x] **Phase 2: Modular AI Integration** (Gemini support, v2 SDK). +- [x] **Phase 3: AI Onboarding UI** (Validation Mask, Camera integration). - [x] **Phase 4: Offline Synchronization** (Deduplicated Dexie -> SQL sync logic). - [x] **Phase 5: Inventory Trash Management** (Waste/Discard/Damage workflow). - [ ] **Phase 6: Audit Log Dashboard UI** (Visual historical interventions). -## 5. Security & Infrastructure -- **Unified SSL Proxy:** Integrated `local-ssl-proxy` for HTTPS access (Camera/Mic) on port 3003. -- **VENV Isolation:** Automated `.venv` management in `start_server.sh`. +*(Note: Completed phases are periodically moved to `dev_docs/PLAN_HISTORY.md` according to AI_RULES)* diff --git a/PROJECT_ARCHITECTURE.md b/PROJECT_ARCHITECTURE.md new file mode 100644 index 00000000..5209c670 --- /dev/null +++ b/PROJECT_ARCHITECTURE.md @@ -0,0 +1,54 @@ +# TFM aInventory - Project Architecture & Requirements + +This document is the **Single Source of Truth** for the project's technical architecture, business requirements, and core logic. + +## 1. Application Overview +A unified system to maintain an inventory of "items" and their quantities, inclusive of a web administration interface, offline field operations, audit logging, and AI-powered label extraction functionalities. + +## 2. Technical Stack +### 2.1 Backend (API & Data) +- **Language:** Python 3.12+ (Optimized for performance and type safety) +- **Framework:** FastAPI (Async ASGI) +- **Database:** SQLite (SQLAlchemy) - Local file-based persistence +- **Validation:** Pydantic v2 +- **Auth:** Hybrid LDAP (python-ldap) + PBKDF2 local password hash caching +- **AI Engine:** Google GenAI SDK (Gemini 2.0 Flash) - Location: `backend/ai/` + +### 2.2 Frontend (Web & PWA) +- **Architecture:** Next.js 15+ (App Router) +- **Styling:** Tailwind CSS (Readability-first config) +- **Icons:** Lucide Icons (React components) +- **Offline persistence:** Dexie.js (IndexedDB wrapper) +- **Scanner:** `html5-qrcode` (Client-side, offline-only) +- **Sync:** Axios with bulk-sync idempotency (UUID-based) + +### 2.3 Operations & Tooling +- **PWA Deployment:** `next-pwa` (Service Workers + Manifest.json) +- **HTTPS Proxy:** `local-ssl-proxy` (Required for mobile camera access, Port 3003) +- **Servers:** Frontend (`npm run dev` on 3000), Backend (`./start_server.sh` on 8000) + +## 3. Data Models & Entities +- **Item:** Name, Category Group (Structured), Item Type (Specific), Quantity, Barcode, Part Number. +- **Category:** Predefined groups for organizational structure. +- **Intervention:** Linked to a required items list. +- **Audit Log:** Immutable ledger detailing CRUD operations and stock fluctuations. + +## 4. Scanning & Optimization Strategy (Crucial) +### 4.1 AI Usage Policy +- **Routine Operations (Check-in/Out):** Executes entirely on the local device unconditionally using `html5-qrcode` ($0 cost). No AI is allowed here. +- **New Item Onboarding (AI Label OCR):** Uses cloud AI (`gemini-2.0-flash`). The user takes a photo, AI extracts data based on strict templates. +- **Validation Mask:** AI-extracted data is NEVER saved directly. It is presented in a validation UI for human confirmation. + +### 4.2 Scanner Technical Specs (FROZEN) +- **Hardware Access:** Direct `MediaStreamTrack` access. Zoom cycle: 1x -> 2x -> Max/2 -> Max. +- **Image Pre-processing:** Rescaling (1200px), 60% Center Crop, Grayscale/Contrast filters, JPEG (`0.85` quality). +- **OCR Matching Engine (`page.tsx`):** + - Noise Filtering: Ignores `< 3` chars, decimals, and dates. + - Scoring: Exact S/N (+500), Exact P/N (+200), Token match (+50), Category match (+20). + - Threshold: Minimum **40 points** for auto-match without user intervention. + +## 5. Offline Sync Protocol +To prevent data loss in basements or unstable networks: +- **Offline Engine:** Service Workers cache assets. IndexedDB saves data. +- **UUID Labeling:** Every sync operation generated offline is tagged with a client-side UUID. +- **Idempotent Backend:** The `bulk_sync` endpoint checks UUIDs against `AuditLog` before applying increments, preventing double-counts. diff --git a/VERSION.json b/VERSION.json index 6e4d91bb..a07dda21 100644 --- a/VERSION.json +++ b/VERSION.json @@ -1,8 +1,9 @@ { - "version": "1.2.7", - "last_build": "2026-04-11-1216", - "commit": "e8f7d", + "version": "1.2.8", + "last_build": "2026-04-11-1225", + "commit": "ab3c9", "changelog": [ + "v1.2.8: Absolute Documentation Consolidation (Unified ARCHITECTURE and AI_RULES)", "v1.2.7: Documentation Refactor: Created TECH_STACK.md for SSOT and removed absolute paths", "v1.2.6: Hotfix - Added missing icon imports (Layers, ChevronDown)", "v1.2.5: Synchronized icons across UI (Layers for Categories, Package for Item Types)", @@ -10,8 +11,6 @@ "v1.2.3: System-wide UI consistency (standardized font sizes, removed uppercase)", "v1.2.2: UI Readability refactor (Removed uppercase/tracking, increased font sizes)", "v1.2.1: Git path persistence, master/dev/vX branching, and UI case-sensitivity fix", - "v1.2.0: Structured category management with grouping support", - "v1.1.0: Multi-user auth & LDAP framework integration", - "v1.0.0: Initial PWA inventory launch" + "v1.2.0: Structured category management with grouping support" ] } diff --git a/dev_docs/ARCHIVE_LOGS.md b/dev_docs/ARCHIVE_LOGS.md index f416567b..43a56554 100644 --- a/dev_docs/ARCHIVE_LOGS.md +++ b/dev_docs/ARCHIVE_LOGS.md @@ -1,3 +1,16 @@ +### [2026-04-11 12:25] v1.2.8: Absolute Documentation Consolidation +**Purpose:** Restructured all project documentation to completely eliminate redundancy and establish clear "Single Source of Truth" boundaries for humans and AI agents. +**Actions:** +- Created `PROJECT_ARCHITECTURE.md` uniting business requirements, tech stack, data models, and specific OCR algorithms. +- Unified all AI operational rules, constraints, and UI fidelities strictly inside `AI_RULES.md`. +- Removed redundant, overlapping files (`GEMINI.md`, `requirements.md`, `TECH_STACK.md`, `UI_FIDELITY_SPEC.md`, `SCANNER_LOGIC_SPEC.md`). +- Stripped `PLAN.md` down to just the active checklist. +**Modified Files:** +- `PROJECT_ARCHITECTURE.md` (New) +- `AI_RULES.md` +- `PLAN.md` +- `VERSION.json` + ### [2026-04-11 12:15] v1.2.7: Documentation Refactor & Portability **Purpose:** Consolidated technical stack information into a single source of truth (`dev_docs/TECH_STACK.md`) and removed absolute paths from all AI-facing documents to ensure the project can be moved across environments without breaking references. **Modified Files:** diff --git a/dev_docs/SCANNER_LOGIC_SPEC.md b/dev_docs/SCANNER_LOGIC_SPEC.md deleted file mode 100644 index 0edc40ac..00000000 --- a/dev_docs/SCANNER_LOGIC_SPEC.md +++ /dev/null @@ -1,36 +0,0 @@ -# TFM aInventory - Scanner Technical Specification (v1.2) - -This document defines the "Frozen" parameters for the scanner component. Do NOT modify these values without explicit user approval. - -## 1. Hardware Access -- **API**: Direct `MediaStreamTrack` access for high-performance camera control. -- **Zoom**: Dynamic detection of `capabilities.zoom.max`. -- **Zoom Cycle**: 1x -> 2x -> Max/2 -> Max. - -## 2. Image Pre-processing (The OCR "Secret Sauce") -Before being sent to Tesseract.js, every frame undergoes these transformations: -- **Rescaling**: Fixed canvas width of **1200px** (Optimal for Mobile RAM/Accuracy). -- **Cropping**: **60% Center Crop** of the video stream (forces focus & removes peripheral noise). -- **Filters**: `grayscale(100%) contrast(180%) brightness(105%)`. -- **Format**: High-quality JPEG (`0.85` quality) via `toDataURL`. - -## 3. OCR Matching Engine (page.tsx) -- **Sanitization**: Text normalized to UPPERCASE, non-alphanumeric replaced with spaces. -- **Noise Filtering**: - - Tokens < 3 chars ignored. - - Decimals (e.g., `0.11`, `0.18`) ignored via regex: `/^\d+\.\d+$/`. - - Dates (e.g., `2024-07-25`) ignored via regex: `/^\d{2,4}-\d{2}-\d{2}$/`. -- **Scoring System**: - - **Exact Serial Number Match**: +500 points (Instant Match). - - **Exact Part Number Match**: +200 points. - - **Token match (e.g., "LC" in "LC/UPC")**: +50 points. - - **Category Match**: +20 points. -- **Threshold**: Minimum **40 points** required for automatic match without user intervention. - -## 4. UI/UX Flow -1. **Auto-Match**: Attempt to identify item immediately from raw text. -2. **Interactive Selection (Fallback)**: If match confidence is low, freeze frame and show clickable bounding boxes for manual word selection. - ---- -*Created: 2026-04-10* -*Status: FROZEN* diff --git a/dev_docs/TECH_STACK.md b/dev_docs/TECH_STACK.md deleted file mode 100644 index 39527796..00000000 --- a/dev_docs/TECH_STACK.md +++ /dev/null @@ -1,25 +0,0 @@ -# TECHNICAL STACK - SINGLE SOURCE OF TRUTH - -This document defines the official technology stack for the Inventory System. All components must adhere to these versions and libraries. - -## 🟢 Backend (API & Data) -- **Language:** Python 3.12+ (Optimized for performance and type safety) -- **Framework:** [FastAPI](https://fastapi.tiangolo.com/) (Async ASGI) -- **Database:** SQLite (SQLAlchemy) - Local file-based persistence -- **Validation:** Pydantic v2 -- **Auth:** Hybrid LDAP (python-ldap) + PBKDF2 local password hash caching (v1.2.4) -- **AI Engine:** Google GenAI SDK (Gemini 2.0 Flash) - Location: `backend/ai/` - -## 🔵 Frontend (Web & PWA) -- **Architecture:** [Next.js](https://nextjs.org/) 15+ (App Router) -- **Styling:** Tailwind CSS (Readability-first config: No uppercase/tracking-widest) -- **Icons:** [Lucide Icons](https://lucide.dev/) (React components) -- **Offline persistence:** [Dexie.js](https://dexie.org/) (IndexedDB wrapper) -- **Scanner:** `html5-qrcode` (Client-side, offline-only) -- **Sync:** Axios with bulk-sync idempotency (UUID-based) - -## 🏗 Operations & Tooling -- **PWA Deployment:** `next-pwa` (Service Workers + Manifest.json) -- **HTTPS Proxy:** `local-ssl-proxy` (Required for mobile camera access) -- **Version Control:** Git (Local-first, path in `.git_path`) -- **Isolation:** Python `.venv` and Node `node_modules` diff --git a/dev_docs/UI_FIDELITY_SPEC.md b/dev_docs/UI_FIDELITY_SPEC.md deleted file mode 100644 index d9624c70..00000000 --- a/dev_docs/UI_FIDELITY_SPEC.md +++ /dev/null @@ -1,12 +0,0 @@ -# UI Fidelity Specification - -This document details the mandatory visual and structural specifications for UI components (headers, banners, cards, buttons) in the unified PWA interface. - -## 1. General Principles -- Use TailwindCSS (or equivalent local vanilla CSS framework established). -- No emojis; strictly Bootstrap Icons. -- Standard spacing, consistent font weight (Inter or Roboto). -- Responsive: Viewport scaling for both Desktop dashboard and Mobile full-screen scanning modes. - -## 2. Specific Components -*(To be populated as components are developed)* diff --git a/requirements.md b/requirements.md deleted file mode 100644 index a1ab88c2..00000000 --- a/requirements.md +++ /dev/null @@ -1,34 +0,0 @@ -# Inventory Application Requirements - -## 1. Description -A unified system to maintain an inventory of "items" and their quantities, inclusive of a web administration interface, offline field operations, audit logging, and AI-powered label extraction functionalities. - -## 2. Core Constraints & System Elements - -### 2.1 Main Application Server (Linux Backend) -See [dev_docs/TECH_STACK.md](dev_docs/TECH_STACK.md) for detailed backend specifications. -- **Target Environment:** Dockerized Linux Environment. -- **Users & Security:** Support multiple authenticated users (PBKDF2 local + optional LDAP). -- **Audit Compliance:** All operations maintain a strict audit log (unique UUIDs, details). - -### 2.2 Client Interface (PWA - Progressive Web App) -See [dev_docs/TECH_STACK.md](dev_docs/TECH_STACK.md) for frontend libraries and architecture. -- **Offline Mode:** Service Workers and local browser storage (IndexedDB) must cache the inventory catalog. -- **Hardware Access:** Must natively tap into the device's camera via HTML5 APIs. - -### 2.3 Scanning & AI processing Cost-Optimization Strategy (Crucial) -* **Routine Operations (Check-in / Check-out):** Utilize client-side, offline Javascript libraries (e.g., `html5-qrcode`) to read 1D/2D barcodes directly in the browser's camera. This executes entirely on the local device unconditionally and uses no AI cloud credits. -* **New Item Onboarding (AI Label OCR):** When an unknown label is encountered or a specific new item is being created, the user takes a high-res photo. This photo is sent to the backend, which proxies a minimal request to a Cloud AI API (e.g., OpenAI / GPT-4 Vision). -* **Template Extraction:** The AI performs standard OCR & structure extraction based on strict prompting templates. The parsed elements are transmitted back to the client interface. -* **Validation Mask:** The client interface explicitly presents a selection mask. The user selects which parsed strings/fields map to specific Item properties (e.g., identifying the actual serial number while discarding vendor identifiers) before committing the Item to the database. - -### 2.4 Data Models & Entities -* **Item:** Name, Category Group (Structured), Item Type (Specific), Quantity, Barcode, Part Number. -* **Category:** Predefined groups for organizational structure (e.g., Connectors, Tools). -* **Intervention:** Linked to a required items list. -* **Audit Log:** Immutable ledger detailing CRUD operations and stock fluctuations. - -### 2.5 Workflows & Reporting -* **Reports:** Quantity aggregates across all items/categories, with historical tracking of item usage intervals (last month, last 6 months, last year). -* **Notifications:** Alert generation when stock drops below minimum quantities. -* **Intervention Planning:** Loading intervention lists (Text/Scanning). Check-outs must fulfill matching lists incrementally, while Check-ins reconcile unused stock.