Build [v1.5.0] - Box Management & Label Printing
This commit is contained in:
Daniel Bedeleanu
58
dev_docs/BOX_SCANNING_MASTER_PLAN.md
Normal file
58
dev_docs/BOX_SCANNING_MASTER_PLAN.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# MASTER PLAN: Box/Container Scanning & Printing Architecture
|
||||
|
||||
Acest plan detaliat descrie arhitectura tehnică și etapele procedurale necesare pentru a echipa sistemul TFM aInventory cu funcționalități de recunoaștere a cutiilor (Box Scanning). Este structurat astfel încât orice AI să poată prelua dezvoltarea exact din punctul în care a fost oprită.
|
||||
|
||||
---
|
||||
|
||||
## Etapele Implementării
|
||||
|
||||
### ETAPA 1: Local OCR Box Scanning (Funcționalitate Principală)
|
||||
|
||||
Această etapă extinde logica existență a scanner-ului pentru a citi local (via `Tesseract.js` pe frontend) textul generic scris pe cutii și a direcționa utilizatorul automat spre inventarul acelei cutii.
|
||||
|
||||
#### Pasul 1.1: Backend și Modele de Date
|
||||
* **Database Migration**: Rularea efectivă (prin `sqlite3 / bash`) pe baza de date de producție a unui query: `ALTER TABLE items ADD COLUMN box_label TEXT;`
|
||||
* **File `backend/models.py`**: Adăugarea coloanei `box_label = Column(String, index=True, nullable=True)` în modelul `Item`.
|
||||
* **File `backend/schemas.py`**: Expoziția acesteia prin Pydantic: `box_label: Optional[str] = None` în `ItemBase`.
|
||||
* **File `backend/routers/items.py`**: Maparea noului câmp la crearea și editarea de itemi, dar **CRITIC**: actualizarea snapshot-urilor JSON de audit (`AuditLogs`), adăugând `"box_label": db_item.box_label` la istoricul imuabil.
|
||||
|
||||
#### Pasul 1.2: Frontend Offline Storage & Formulare UI
|
||||
* **File `frontend/lib/db.ts`**: Adăugarea `box_label?: string;` în interfața TypeScript `Item`. Upgrade la _Dexie database version_ pentru indexarea `items: '++id, barcode, name, category, box_label, ...'`.
|
||||
* **File `frontend/components/AIOnboarding.tsx` & `page.tsx` (Meniul de Editare)**:
|
||||
* Adăugarea câmpului UI "Box/Container Label".
|
||||
* Câmpul devine un `datalist` dropdown conectat la un array derivat `existingBoxes`: `Array.from(new Set(inventory.map(i => i.box_label).filter(Boolean)))`.
|
||||
* Asta permite la Onboarding selecția rapidă dintr-o listă a unei cutii deja utilizate.
|
||||
* **File `frontend/app/page.tsx` (Bara de Căutare Generală)**: Extinderea filtrelor de vizibilitate `inventory.filter()` pentru a include textul introdus în caseta de căutare principală dacă matcheaza cu un `box_label`.
|
||||
|
||||
#### Pasul 1.3: Router-ul de Inteligență al Scannerului (`onOCRMatch`)
|
||||
* **Fișier Principal `frontend/app/page.tsx`**: Acolo unde rulează bucla `Scanner.tsx` OCR o dată la 4 secunde, se injectează logica nouă de intercepție în `onOCRMatch()`.
|
||||
* **Logica Funcțională**:
|
||||
1. **Fuzzy String Match**: Compară masiv șirul dezordonat venit de la cameră cu toate `item.box_label` existente.
|
||||
2. Filtrăm array-ul temporar `possibleBoxMatches`.
|
||||
3. Dacă `possibleBoxMatches.length === 1`: Sistemul selectează instant acel produs -> `setShowScanner(false); setSelectedItem(match);`. Trecere directă la editare stoc (din cauză că este o cutie dedicată).
|
||||
4. Dacă `possibleBoxMatches.length > 1`: S-a recunoscut "cutia cu SFP-uri" care conține 5 modele diferite. Sistemul va popa un **Modal Interstitial NOU: "Alegeți Item-ul din Cutie"**. Acest modal randează un array vizual ca meniu. Odată făcut click pe un item, deschide panoul de CheckIn/Out pentru el.
|
||||
5. Dacă cutia nu matchează cu niciun `box_label`, dă `fallback` la logica clasică de `onOCRMatch` (să recunoască S/N-ul individual sau Part Number-ul exact).
|
||||
|
||||
---
|
||||
|
||||
### ETAPA 2: Sistem de Generare și Printare Etichete pe Cutii (Funcționalitate Secundară)
|
||||
|
||||
Misiunea de a crea un cod unic perfect (lipsit de ratele de eroare ale OCR-ului generic) pentru cutii, pe care angajații să îl poată printa direct pe o imprimantă Dymo/Brother sau descărca ca poză.
|
||||
|
||||
#### Pasul 2.1: Identificatori Generatori Vizuali
|
||||
* **Logică PWA**: Nu vom rula backend separat pentru imagini; le vom genera via HTML Canvas pe Frontend pentru lățime de bandă 0.
|
||||
* **Dependință Nouă UI**: Instalarea `react-barcode` / `qrcode.react` pe frontend pentru desenarea instantanee vizuală bazată pe șirul textual din `box_label` (ex: textul "SFPx5-BOX" -> devine un QRCode valid).
|
||||
|
||||
#### Pasul 2.2: Managementul Meniului de Printare
|
||||
* Afișare Modul `[📦 Tablou Cutii]`, vizibil din Setări/Admin sau în meniul Item-urilor, care grupează itemii per `box_label`.
|
||||
* Fiecare categorie de "cutie" are buton dedicat: **[Printează Etichetă (Generează Cod)]**.
|
||||
* **Metoda Multi-Platformă**:
|
||||
* Când este apăsat generăm un obiect izolat DOM (div hidden).
|
||||
* Folosim clase CSS media de izolare `@media print { @page { size: 62mm 29mm; } body * { display: none; } #print-area { display: block; } }`.
|
||||
* Asta triggerează popup-ul de print nativ MacOS/Windows perfect adaptat unei imprimante etichetatoare de birou Dymo/Brother.
|
||||
* **Fallback Mobil (iOS/Android)**: Lângă opțiunea de "Print direct", adăugăm buton de **[Salvează pe Telefon (Imagine.png)]**. Utilizatorul transferă imaginea perfect rasterizată (canvas via `toDataURL()`) în rola foto pentru a deschide aplicația portabilă proprietară de print Bluetooth (ex: Niimbot app).
|
||||
|
||||
|
||||
## Validarea Aprobării
|
||||
> [!IMPORTANT]
|
||||
> REGULA DE AUR PENTRU AI: Nu ai voie să scrii cod din acest plan dacă utilizatorul nu a aprobat explicit începerea implementării Etapelor! Citește acest document ori de câte ori continui logica sistemului PWA aInventory.
|
||||
@@ -7,45 +7,41 @@
|
||||
|
||||
---
|
||||
|
||||
## STATUS: 🟢 STABLE — SECURITY HARDENING & PWA OPTIMIZATION COMPLETE
|
||||
## STATUS: 🟢 STABLE — BOX MANAGEMENT & LABEL PRINTING COMPLETE (v1.5.0)
|
||||
|
||||
The TFM aInventory v1.4.0 is now fully hardened, tested, and optimized for mobile/enterprise use. All security vulnerabilities identified in the audit have been addressed, and the UI has been upgraded to a high-fidelity "Premium" standard.
|
||||
The TFM aInventory v1.5.0 has been upgraded with a powerful local-first Box/Container management system. Users can now group items into boxes, identify them instantly via local OCR, and print physical Barcode/QR labels directly from the PWA.
|
||||
|
||||
---
|
||||
|
||||
## WHAT WAS DONE THIS SESSION
|
||||
|
||||
### 1. Security Hardening (Backend)
|
||||
- **Rate Limiting** — Implemented `slowapi` on `/users/login` (5 req/min) to prevent brute-force attacks.
|
||||
- **RBAC Enforcement** — Restricted `DELETE /items/` exclusively to the **Admin** role.
|
||||
- **Sensitive Data** — Scrubbed `JWT_SECRET_KEY` and other sensitive snippets from debug logs.
|
||||
- **REST API Testing** — Developed an automated Python test suite (`backend/tests/api_bench.py`) to verify Auth, RBAC, and Rate Limiting. Confirmed all **PASS**.
|
||||
### 1. Box Management Architecture (Backend)
|
||||
- **Database Schema** — Added `box_label` column to the `items` table.
|
||||
- **Audit Integrity** — Updated `AuditLog` snapshots to capture `box_label` at the time of each transaction, ensuring immutable historical traceability even if items are moved.
|
||||
- **API Support** — Exposed `box_label` in Pydantic schemas and item routers.
|
||||
|
||||
### 2. Admin & LDAP Integration
|
||||
- **Dual Group Mapping** — Restored the UI fields for strictly mapping separated Admin and User groups in LDAP.
|
||||
- **TLS Configuration** — Replaced the text link with a high-visibility **Switch Component** for TLS activation.
|
||||
- **State Cleanup** — Fixed initialization bugs where the Enterprise card wouldn't load from disk correctly.
|
||||
### 2. Intelligent Scanner Routing (Frontend)
|
||||
- **Box Match Priority** — Rewrote the scanner's `onOCRMatch` logic to prioritize box labels.
|
||||
- **Multi-Item Support** — Developed a "Box Contents" interstitial modal that handles containers with multiple distinct item types.
|
||||
- **Token Matching** — Implemented a local fuzzy token-matching engine for generic box text recognition without AI costs.
|
||||
|
||||
### 3. PWA & Mobile Expert Audit
|
||||
- **Icon Assets** — Generated missing PWA icons (192, 512, maskable) from the source logo using `sips`.
|
||||
- **Manifest Upgrade** — Added "Maskable" icon support, orientation lock, and app shortcuts.
|
||||
- **iOS Support** — Added Apple-specific meta tags (`apple-mobile-web-app-capable`, status bar styles) for a native experience on iPhone.
|
||||
### 3. Dependency-Free Label System
|
||||
- **Native Generation** — Built a zero-dependency SVG engine for Code 128 Barcodes and QR Codes (`lib/labels.ts`).
|
||||
- **Box Manager Dashboard** — Added a dedicated UI to view all existing boxes and trigger label generation.
|
||||
- **Hybrid Printing** — Implemented CSS `@media print` for professional desktop printers and "Save as PNG" rasterization for portable Bluetooth printers on mobile.
|
||||
|
||||
### 4. Modern CSS & Visual Excellence
|
||||
- **Glassmorphism** — Created and applied a custom `.glass-card` utility (backdrop-blur-xl + subtle gradients) to all primary UI sections.
|
||||
- **Safe Areas** — Implemented `pb-safe` to ensure bottom navigation doesn't overlap with iOS home bars.
|
||||
- **Fluid Typography** — Added `clamp()` based scaling for better readability across devices.
|
||||
|
||||
### 5. Production Export Cleanup
|
||||
- **`export_prod.sh`** — Updated to explicitly exclude `tests/` folders and development benchmarking scripts.
|
||||
- **New Bundle** — Generated a clean **`aInventory-PROD-v1.4.0.zip`**.
|
||||
### 4. UI/UX Excellence
|
||||
- **Search Integration** — Integrated `box_label` into the global search filter.
|
||||
- **Onboarding Support** — Added Box Label association to the AI-powered onboarding workflow with smart `datalist` suggestions.
|
||||
- **Visual Polish** — Applied Lucide `Package` iconography and consistent branding to the new modules.
|
||||
|
||||
---
|
||||
|
||||
## WHAT THE NEXT AI MUST DO
|
||||
|
||||
1. **Database Encryption** — Consider implementing SQLite encryption at rest (SQLCipher) as per the security report.
|
||||
1. **Database Encryption** — Consider implementing SQLite encryption at rest (SQLCipher) if requested.
|
||||
2. **Persistent JWT** — If requested, move the `JWT_SECRET_KEY` to a `.env` file for session persistence across server restarts.
|
||||
3. **Advanced Filtering** — Extend the Box Manager to allow bulk movements between boxes.
|
||||
3. **LDAP Probe** — The "Test Connection" button may show "Partial Success" (handshake rejected) due to anonymous bind restrictions; login itself works fine.
|
||||
4. **Monitoring** — If the rate limiter triggers too frequently for legitimate users, adjust the `slowapi` limit in `backend/routers/users.py`.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user