From a4783bea2cb37f20cc50cd71ed871bfc6bf4c8d0 Mon Sep 17 00:00:00 2001 From: "Adrian A. Baumann" Date: Thu, 1 Jan 2026 16:42:17 +0100 Subject: [PATCH] Agents file updated --- AGENTS.md | 179 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 150 insertions(+), 29 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b727bc7..6107d61 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ This document provides guidelines for AI coding agents working in the labhelper ## Project Overview -- **Type**: Django web application +- **Type**: Django web application (lab inventory management system) - **Python**: 3.13.7 - **Django**: 5.2.9 - **Database**: SQLite (development) @@ -66,6 +66,21 @@ python manage.py collectstatic # Collect static files gunicorn labhelper.wsgi:application # Run with Gunicorn ``` +### Custom Management Commands + +```bash +# Create default users and groups +python manage.py create_default_users + +# Clean up orphaned files from deleted things +python manage.py clean_orphaned_files +python manage.py clean_orphaned_files --dry-run + +# Clean up orphaned images and thumbnails +python manage.py clean_orphaned_images +python manage.py clean_orphaned_images --dry-run +``` + ## Code Style Guidelines ### Python Style @@ -178,23 +193,85 @@ def get_box(request: HttpRequest, box_id: int) -> HttpResponse: ``` labhelper/ -├── manage.py # Django CLI entry point -├── requirements.txt # Python dependencies -├── labhelper/ # Project configuration -│ ├── settings.py # Django settings -│ ├── urls.py # Root URL routing -│ ├── wsgi.py # WSGI application -│ └── asgi.py # ASGI application -└── boxes/ # Django app - ├── admin.py # Admin configuration - ├── apps.py # App configuration - ├── models.py # Data models - ├── views.py # View functions - ├── tests.py # Test cases - ├── migrations/ # Database migrations - └── templates/ # HTML templates +├── .gitea/ +│ └── workflows/ +│ └── build-containers-on-demand.yml # CI/CD workflow +├── argocd/ # Kubernetes deployment manifests +│ ├── 001_pvc.yaml # PersistentVolumeClaim +│ ├── deployment.yaml # Deployment + Service +│ ├── ingress.yaml # Traefik ingress +│ ├── nfs-pv.yaml # NFS PersistentVolume +│ ├── nfs-storageclass.yaml # NFS StorageClass +│ └── secret.yaml # Django secret key template +├── boxes/ # Main Django app +│ ├── management/ +│ │ └── commands/ +│ │ ├── clean_orphaned_files.py # Cleanup orphaned ThingFile attachments +│ │ └── clean_orphaned_images.py # Cleanup orphaned Thing images +│ ├── migrations/ # Database migrations +│ ├── templates/ +│ │ └── boxes/ +│ │ ├── add_things.html # Form to add multiple things +│ │ ├── box_detail.html # Box contents view +│ │ ├── box_management.html # Box/BoxType CRUD management +│ │ ├── index.html # Home page +│ │ ├── search.html # Search page with AJAX +│ │ ├── thing_detail.html # Thing details view +│ │ └── thing_type_detail.html # Thing type hierarchy view +│ ├── templatetags/ +│ │ └── dict_extras.py # Custom template filter: get_item +│ ├── admin.py # Admin configuration +│ ├── apps.py # App configuration +│ ├── forms.py # All forms and formsets +│ ├── models.py # Data models +│ ├── tests.py # Test cases +│ └── views.py # View functions +├── data-loader/ # Init container for database preload +│ ├── Dockerfile # Alpine-based init container +│ └── preload.sqlite3 # Preloaded database for deployment +├── labhelper/ # Project configuration +│ ├── management/ +│ │ └── commands/ +│ │ └── create_default_users.py # Create default users/groups +│ ├── templates/ +│ │ ├── base.html # Base template with navigation +│ │ └── login.html # Login page +│ ├── asgi.py # ASGI configuration +│ ├── settings.py # Django settings +│ ├── urls.py # Root URL configuration +│ └── wsgi.py # WSGI configuration +├── scripts/ +│ ├── deploy_secret.sh # Generate and deploy Django secret +│ ├── full_deploy.sh # Bump both container versions + copy DB +│ └── partial_deploy.sh # Bump main container version only +├── .gitignore +├── AGENTS.md # This file +├── Dockerfile # Multi-stage build for main container +├── manage.py # Django CLI entry point +└── requirements.txt # Python dependencies ``` +## Data Models + +### boxes app + +| Model | Description | Key Fields | +|-------|-------------|------------| +| **BoxType** | Type of storage box with dimensions | `name`, `width`, `height`, `length` (in mm) | +| **Box** | A storage box in the lab | `id` (CharField PK, max 10), `box_type` (FK) | +| **ThingType** | Hierarchical category (MPTT) | `name`, `parent` (TreeForeignKey to self) | +| **Thing** | An item stored in a box | `name`, `thing_type` (FK), `box` (FK), `description`, `picture` | +| **ThingFile** | File attachment for a Thing | `thing` (FK), `file`, `title`, `uploaded_at` | +| **ThingLink** | Hyperlink for a Thing | `thing` (FK), `url`, `title`, `uploaded_at` | + +**Model Relationships:** +- BoxType -> Box (1:N via `boxes` related_name, PROTECT on delete) +- Box -> Thing (1:N via `things` related_name, PROTECT on delete) +- ThingType -> Thing (1:N via `things` related_name, PROTECT on delete) +- ThingType -> ThingType (self-referential tree via MPTT) +- Thing -> ThingFile (1:N via `files` related_name, CASCADE on delete) +- Thing -> ThingLink (1:N via `links` related_name, CASCADE on delete) + ## Available Django Extensions The project includes these pre-installed packages: @@ -206,6 +283,11 @@ The project includes these pre-installed packages: - **django-nested-inline**: Additional nested inline support - **django-revproxy**: Reverse proxy functionality - **sorl-thumbnail**: Image thumbnailing +- **Pillow**: Image processing +- **gunicorn**: Production WSGI server +- **Markdown**: Markdown processing +- **bleach**: HTML sanitization +- **coverage**: Test coverage - **Font Awesome**: Icon library (loaded via CDN) - **jQuery**: JavaScript library (loaded via CDN) @@ -287,15 +369,27 @@ The project uses a base template system at `labhelper/templates/base.html`. All ### Available Pages/Views -| View Name | URL Pattern | Description | -|-----------|--------------|-------------| -| `index` | `/` | Home page with boxes grid and thing types tree | -| `box_detail` | `/box//` | List items in a specific box | -| `thing_detail` | `/thing//` | Thing details with move-to-box form | -| `thing_type_detail` | `/thing-type//` | Thing type hierarchy and items | -| `add_things` | `/box//add/` | Form to add/edit items in a box | -| `search` | `/search/` | Search page with AJAX autocomplete | -| `search_api` | `/search/api/` | AJAX endpoint for search results | +| View Function | URL Pattern | Name | Description | +|---------------|-------------|------|-------------| +| `index` | `/` | `index` | Home page with boxes grid and thing types tree | +| `box_management` | `/box-management/` | `box_management` | Manage boxes and box types | +| `add_box_type` | `/box-type/add/` | `add_box_type` | Add new box type | +| `edit_box_type` | `/box-type//edit/` | `edit_box_type` | Edit box type | +| `delete_box_type` | `/box-type//delete/` | `delete_box_type` | Delete box type | +| `add_box` | `/box/add/` | `add_box` | Add new box | +| `edit_box` | `/box//edit/` | `edit_box` | Edit box | +| `delete_box` | `/box//delete/` | `delete_box` | Delete box | +| `box_detail` | `/box//` | `box_detail` | View box contents | +| `thing_detail` | `/thing//` | `thing_detail` | View/edit thing (move, picture, files, links) | +| `thing_type_detail` | `/thing-type//` | `thing_type_detail` | View thing type hierarchy | +| `add_things` | `/box//add/` | `add_things` | Add multiple things to a box | +| `search` | `/search/` | `search` | Search page | +| `search_api` | `/search/api/` | `search_api` | AJAX search endpoint | +| `LoginView` | `/login/` | `login` | Django auth login | +| `LogoutView` | `/logout/` | `logout` | Django auth logout | +| `admin.site` | `/admin/` | - | Django admin | + +**All views except login require authentication via `@login_required`.** ### Template Best Practices @@ -336,6 +430,33 @@ The project uses a base template system at `labhelper/templates/base.html`. All

``` +## Forms + +| Form | Model | Purpose | +|------|-------|---------| +| `ThingForm` | Thing | Add/edit a thing (name, type, description, picture) | +| `ThingPictureForm` | Thing | Upload/change thing picture only | +| `ThingFileForm` | ThingFile | Add file attachment | +| `ThingLinkForm` | ThingLink | Add link | +| `BoxTypeForm` | BoxType | Add/edit box type | +| `BoxForm` | Box | Add/edit box | +| `ThingFormSet` | Thing | Formset for adding multiple things | + +## Management Commands + +### boxes app + +| Command | Description | Options | +|---------|-------------|---------| +| `clean_orphaned_files` | Clean up orphaned files from deleted things | `--dry-run` | +| `clean_orphaned_images` | Clean up orphaned images and thumbnails | `--dry-run` | + +### labhelper project + +| Command | Description | +|---------|-------------| +| `create_default_users` | Create default users and groups (admin/admin123, staff/staff123, viewer/viewer123) | + ## Testing Guidelines - Use `django.test.TestCase` for database tests @@ -374,10 +495,10 @@ Per `.gitignore`: 1. **NEVER commit or push without explicit permission**: Always ask the user before running `git commit` or `git push`. The user will explicitly say "commit and push" when they want you to do this. Do NOT automatically commit/push after making changes unless instructed to do so. 2. **Always activate venv**: `source .venv/bin/activate` 3. **Run migrations after model changes**: `makemigrations` then `migrate` -3. **Add new apps to INSTALLED_APPS** in `settings.py` -4. **Templates in labhelper/templates/**: The base template and shared templates are in `labhelper/templates/`. App-specific templates remain in `app_name/templates/`. -4. **Use get_object_or_404** instead of bare `.get()` calls -5. **Never commit SECRET_KEY** - use environment variables in production +4. **Add new apps to INSTALLED_APPS** in `settings.py` +5. **Templates in labhelper/templates/**: The base template and shared templates are in `labhelper/templates/`. App-specific templates remain in `app_name/templates/`. +6. **Use get_object_or_404** instead of bare `.get()` calls +7. **Never commit SECRET_KEY** - use environment variables in production ## Deployment Commands