diff --git a/AI_RULES.md b/AI_RULES.md index 7c8ae656..66f8f573 100644 --- a/AI_RULES.md +++ b/AI_RULES.md @@ -1,81 +1,53 @@ -# AI AGENT RULES - MANDATORY ENTRY POINT +# AI AGENT RULES - MANDATORY SSOT ENTRY POINT **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. -(Automatic IDE entry points like `GEMINI.md` and `CLAUDE.md` exist solely to redirect agents to this main file). -For technical architecture, data models, and stack details, refer to [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md). +This is the **Single Source of Truth** for ALL AI agents. Refer to [PROJECT_ARCHITECTURE.md](PROJECT_ARCHITECTURE.md) for technical logic. -## 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, 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. +--- + +## 1. AI MEMORY, TRACEABILITY & HANDOVER +- **MANDATORY STARTUP**: Read `dev_docs/SESSION_STATE.md` immediately at session start. +- **PLAN RETIREMENT**: Mark a completed "Master Plan" as `[COMPLETED]` in the file itself. Move technical details to `dev_docs/ARCHIVE_LOGS.md` and `PLAN.md` entries to `dev_docs/PLAN_HISTORY.md`. +- **STRICT HANDOVER**: Update `dev_docs/SESSION_STATE.md` at the end of every task with: **Active AI**, **Current Status** (Stable/Broken/In-Progress), **Context**, and **Next Steps**. +- **SESSION ARCHIVE**: Move previous handover content to `dev_docs/SESSION_HISTORY.md` before writing new state. - **NO INTERACTION OVERLAP**: Never modify a file if another AI session is explicitly working on it. -## 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). -- **PACKAGE MANAGEMENT**: Any new package installed via `pip install` MUST be added to `backend/requirements.txt` with version constraints (e.g., `slowapi>=0.1.9`). Keep requirements.txt synchronized with installed packages. -- **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. +## 2. ENGINEERING & OPERATIONAL LAWS +- **ENGLISH ONLY**: Interfaces, code, variables, and docs MUST be in English. Translate any Romanian text found in code immediately. (User conversation: Romanian/English). +- **GIT PROTOCOL**: Use binary path in `.git_path` for all operations. Never push or use `--force` unless asked. Branching: `master` (stable), `dev` (active), `vX` (archive). +- **VERSIONING**: Update `VERSION.json` on every commit. Use `scripts/save_version.py` for automated releases. +- **DEPENDENCIES**: Update `backend/requirements.txt` with version constraints for every new pip package. +- **SSOT INTEGRITY**: Every feature change MUST update: `README.md`, `USER_GUIDE.md`, `PROJECT_ARCHITECTURE.md`, and `export_prod.sh`. -## 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`). +## 3. UI/UX "PREMIUM" FIDELITY STANDARDS +- **Aesthetics**: Density/aesthetics must remain "Premium". Use Tailwind CSS. NO simplification. +- **Typography Rules**: + - **NO UPPERCASE** or **NO ITALICS** in headers, labels, buttons, or metadata. + - **NO `tracking-widest`**. Use standard camel/Title case. + - Use `font-black` for main headings. +- **Layout**: Main pages MUST use `max-w-7xl`. +- **Unified Headers**: Icon box (`p-4 bg-primary/10 border-primary/20`) + Title (`text-3xl font-black`) + Subtitle (`text-xs text-slate-500`). +- **Iconography**: Use **Lucide Icons** exclusively (NO emojis). + - **Categories**: `Layers` (text-primary). + - **Item Types**: `Package` (text-green-500). +- **Affordance**: Dropdowns MUST have a `ChevronDown`. Passwords: `text-white/50`. Logout MUST be `text-rose-500`. -## 4. Documentation Maintenance -- **SSOT INTEGRITY**: Whenever a feature is added, modified, or removed, you MUST update all corresponding documentation files: - - `README.md` (General usage & technical modes). - - `USER_GUIDE.md` (End-user instructions). - - `PROJECT_ARCHITECTURE.md` (Technical logic & data models). - - `export_prod.sh` (If new scripts or files must be included in the production bundle). -- **REAL-TIME UPDATES**: Documentation updates are NOT optional and must be performed within the same session as the code changes. +## 4. DATA INTEGRITY & AUDIT POLICY +- **RESTRICTED ACTIONS**: `DELETE /items/` and Admin settings require `auth.get_current_admin`. +- **AUDIT IMMUTABILITY**: Deleting an `Item` MUST NOT delete its `AuditLog` entries. +- **TRACEABILITY**: Log deletions to `logs/backend.log` with `USER[id]`, `ITEM[id]`, `Name`, `PN`. +- **CONFIRMATION**: + - **Triple Confirmation**: Deleting critical entities (Locations/Items) requires user confirmation 3 times. + - **Native Alerts**: Use `window.confirm` for all destructive UI actions and Logout. -## 6. AI Command Shortcuts -- **`save-version`**: When the user triggers this command, the AI MUST: - 1. Increment the patch version in `VERSION.json`. - 2. Stage all current changes (`git add .`). - 3. Commit changes with message `Build [vX.Y.Z]`. - 4. Create a new branch named `vX.Y.Z` from the current state. - 5. Generate a production bundle ZIP (calls `./export_prod.sh`). - 6. Stay on the current branch (`dev`). - - *Implementation*: Use `python3 scripts/save_version.py` to ensure consistency. +## 5. AI COMMAND SHORTCUTS +- **`save-version`**: 1. Increment `VERSION.json`. 2. Git add/commit (`Build [vX.Y.Z]`). 3. Create branch `vX.Y.Z`. 4. Run `./export_prod.sh`. (Always use `python3 scripts/save_version.py`). -## 7. UI Fidelity Laws (Strict) -- **Consistent Layout**: All main pages (Inventory, Audit, Admin) MUST use `max-w-7xl` for their primary content container. -- **Unified Headers**: Every functional page MUST have an identical header structure: - - Icon inside a styled box (`p-4 bg-primary/10 rounded-[2rem] border border-primary/20`). - - Title: `text-3xl font-black text-white tracking-tight`. - - Subtitle: `text-xs text-slate-500 font-bold mt-1 tracking-wider`. -- **Typographic Integrity**: - - **NO UPPERCASE** (ALL CAPS) allowed anywhere in the UI (headers, labels, buttons, metadata). - - **NO ITALICS** in headers, titles, or active UI elements. - - Consistent font weight (`font-black`) for main headings. -- **Safety Actions**: - - The **Logout** button MUST be clearly differentiated (e.g., `text-rose-500`) and MUST always require a `window.confirm` before execution. +--- -## 8. Audit & Deletion Policy -- **Immutability of Logs**: Deleting an `Item` MUST NOT delete its corresponding entries in the `AuditLog` table in the database. -- **Disk Traceability**: Every item deletion MUST be logged to the disk file (`logs/backend.log`) with `USER[id]`, `ITEM[id]`, `Name`, and `PN`. -- **Explicit Confirmation**: Destructive actions (Delete Item from catalog) MUST always trigger a browser-native `window.confirm` before proceeding. - - -## 5. 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 verbatim summaries of the code. +## END OF SESSION PROTOCOL +End your final response on a separate line exactly with: +``` +--- +✓ Done. +``` diff --git a/dev_docs/ARCHIVE_LOGS.md b/dev_docs/ARCHIVE_LOGS.md index 9796cb09..9692f20c 100644 --- a/dev_docs/ARCHIVE_LOGS.md +++ b/dev_docs/ARCHIVE_LOGS.md @@ -1,3 +1,19 @@ +### [2026-04-12] v1.5.0: Box Management, Local OCR & Dependency-Free Label Printing +**Purpose:** Implementation of a local-first box scanning workflow, including multi-item container selection and professional label generation without external libraries. +**Actions:** +- `backend/models.py` & `schemas.py` — Added `box_label` field and integrated it into Pydantic models. +- `backend/routers/items.py` — Updated item creation and deletion to include `box_label` in immutable AuditLog snapshots. +- `frontend/lib/db.ts` — Upgraded IndexedDB (Dexie) to v4 with an index on `box_label` for high-speed local searching. +- `frontend/app/page.tsx` — Rewrote `onOCRMatch` to prioritize box matching. Implemented "Box Contents" selection modal and a full Box Inventory management dashboard. +- `frontend/components/AIOnboarding.tsx` — Added Box Label association to the AI-powered onboarding form. +- `frontend/lib/labels.ts` (NEW) — Developed a 100% dependency-free SVG engine for Barcode 128 and QR Code generation. +- `scripts/save_version.py` — Updated script to automatically synchronize `dev` changes into the `master` branch during releases. +- `AI_RULES.md` — Added Rule 1.1 for mandatory "Plan Retirement" and strict traceability. +- `USER_GUIDE.md` & `PROJECT_ARCHITECTURE.md` — Full documentation of the new container-based logic. +**Status:** Stable. Build v1.5.0 release branch created and merged into Master. + +--- + ### [2026-04-12] v1.4.1: Security Hardening, PWA Optimization & Modern CSS Upgrade **Purpose:** Implementation of security audit recommendations, REST API test suite, PWA asset generation, and visual UI refinements using Modern CSS. **Actions:** diff --git a/dev_docs/BOX_SCANNING_MASTER_PLAN.md b/dev_docs/BOX_SCANNING_MASTER_PLAN.md index fb1664e0..947f769f 100644 --- a/dev_docs/BOX_SCANNING_MASTER_PLAN.md +++ b/dev_docs/BOX_SCANNING_MASTER_PLAN.md @@ -1,6 +1,9 @@ -# MASTER PLAN: Box/Container Scanning & Printing Architecture +# [COMPLETED] 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ă. +> [!IMPORTANT] +> **STATUS: FULLY IMPLEMENTED (v1.5.0)** +> Date: 2026-04-12 +> This plan is no longer active. All phases (OCR, Smart Routing, Label Printing) have been merged into the main codebase. --- diff --git a/dev_docs/SESSION_STATE.md b/dev_docs/SESSION_STATE.md index 7b5aea91..76f66810 100644 --- a/dev_docs/SESSION_STATE.md +++ b/dev_docs/SESSION_STATE.md @@ -9,7 +9,7 @@ ## STATUS: 🟢 STABLE — BOX MANAGEMENT & LABEL PRINTING COMPLETE (v1.5.0) -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. +**CRITICAL FOR NEXT AI:** The "Box/Container Management" feature is **FINISHED**. Do NOT attempt to re-implement or look for a plan. The core logic is already in `frontend/app/page.tsx` (`onOCRMatch` and `BoxManager`), `backend/models.py`, and `frontend/lib/labels.ts`. ---