modificari de documentatii dupa o implementare noua
This commit is contained in:
Daniel Bedeleanu
114
AI_RULES.md
114
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.
|
||||
```
|
||||
|
||||
@@ -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:**
|
||||
|
||||
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user