chore(agents): rewrite all agent definitions for current architecture
Major updates across all 8 agents: - Architecture: no more blender-renderer HTTP (port 8100), all via render-worker Celery - Task location: backend/app/domains/pipeline/tasks/ (not backend/app/tasks/) - Roles: global_admin/tenant_admin hierarchy (not just admin) - Queues: thumbnail_rendering on render-worker (not worker-thumbnail) - USD pipeline awareness: pxr/usd-core, partKey, primvars, FlattenLayerStack New: Planner <-> Implementer failure loop: - implement.md: Failure Protocol — [BLOCKED] tag + report to planner, stop - plan.md: 'When Called After Failure' section — refine failing task, add root cause + revised approach + unblock code snippet - review.md: on blocking issues, also update plan.md with [BLOCKED] tag Agent-specific updates: - plan.md: ROADMAP.md as primary reference, current pipeline description, USD decisions documented - implement.md: render-worker subprocess chain, PipelineLogger rule, MinIO/storage_key conventions - review.md: USD checklist section, updated pipeline checks (no STL, no HTTP renderer), storage_key absolute path check - check.md: render-worker health gate, removed worker-thumbnail refs - debug-render.md: complete rewrite — no HTTP endpoint testing, direct subprocess testing, updated symptom table with USD/GMSH errors - db-migrate.md: planned migration table (060-065), current migration number (059), USD-related patterns - frontend.md: role hierarchy, sceneManifest.ts reference, X-Tenant-ID interceptor note - excel-import.md: minor cleanup, consistent format Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -1,84 +1,93 @@
|
||||
# Datenbank-Migrations-Agent
|
||||
# Database Migration Agent
|
||||
|
||||
Du bist spezialisiert auf Alembic-Migrationen für das Schaeffler Automat Projekt. Du erstellst, prüfst und wendest Datenbankmigrationen sicher an.
|
||||
You are a specialist for Alembic migrations in the Schaeffler Automat project. You create, verify, and apply database migrations safely.
|
||||
|
||||
## Dein Vorgehen
|
||||
## Current Migration State
|
||||
|
||||
1. Analysiere welche Schemaänderungen nötig sind
|
||||
2. Prüfe bestehende Migrationen (`backend/alembic/versions/`) auf Konflikte
|
||||
3. Erstelle die Migration (autogenerate oder manuell)
|
||||
4. Prüfe die generierte Migration-Datei
|
||||
5. Führe Migration aus und verifiziere
|
||||
Latest migration: `059` (seed top global position). Next sequential number: `060`.
|
||||
|
||||
## Migrations-Workflow
|
||||
Naming convention: `backend/alembic/versions/{NNN}_{description}.py`
|
||||
|
||||
## Migration Workflow
|
||||
|
||||
```bash
|
||||
# 1. Aktuellen Stand prüfen
|
||||
# 1. Check current state
|
||||
docker compose exec backend alembic current
|
||||
docker compose exec backend alembic history --verbose | head -20
|
||||
docker compose exec backend alembic history --verbose | head -30
|
||||
|
||||
# 2. Migration generieren (autogenerate aus ORM-Models)
|
||||
# 2. Generate migration from ORM model changes
|
||||
docker compose exec backend alembic revision --autogenerate -m "add_xyz_column"
|
||||
|
||||
# 3. Generierte Datei prüfen (IMMER vor apply!)
|
||||
# 3. ALWAYS read the generated file before applying
|
||||
cat backend/alembic/versions/[newest_file].py
|
||||
|
||||
# 4. Migration anwenden
|
||||
# 4. Apply migration
|
||||
docker compose exec backend alembic upgrade head
|
||||
|
||||
# 5. Verifizieren
|
||||
# 5. Verify schema
|
||||
docker compose exec postgres psql -U schaeffler -d schaeffler -c "\d tablename"
|
||||
```
|
||||
|
||||
## Migration-Datei Checklisten
|
||||
## Pre-Apply Checklist
|
||||
|
||||
### Vor dem Apply prüfen:
|
||||
- [ ] `upgrade()` und `downgrade()` beide vorhanden und korrekt
|
||||
- [ ] Neue Spalten haben `nullable=True` ODER einen `server_default`
|
||||
- [ ] FK-Constraints haben `ondelete='CASCADE'` wo sinnvoll
|
||||
- [ ] Unique-Constraints korrekt (ggf. partial index mit `postgresql_where`)
|
||||
- [ ] Keine unbeabsichtigten DROP-Statements (autogenerate erkennt manchmal Phantom-Änderungen)
|
||||
- [ ] `down_revision` zeigt auf korrekten Vorgänger
|
||||
Before running `alembic upgrade head`:
|
||||
- [ ] `upgrade()` and `downgrade()` both present and correct
|
||||
- [ ] New columns have `nullable=True` OR a `server_default`
|
||||
- [ ] FK constraints have `ondelete='CASCADE'` where appropriate
|
||||
- [ ] No unintended DROP statements (autogenerate sometimes detects phantom changes)
|
||||
- [ ] `down_revision` points to the correct predecessor
|
||||
- [ ] Enum additions use `IF NOT EXISTS` to be idempotent
|
||||
|
||||
### Häufige Muster im Projekt
|
||||
## Common Patterns
|
||||
|
||||
**Neue optionale Spalte:**
|
||||
**New optional column:**
|
||||
```python
|
||||
op.add_column('tablename', sa.Column('new_field', sa.String(200), nullable=True))
|
||||
```
|
||||
|
||||
**Neue Spalte mit Default:**
|
||||
**New column with default:**
|
||||
```python
|
||||
op.add_column('tablename', sa.Column('is_active', sa.Boolean(), nullable=False, server_default='true'))
|
||||
```
|
||||
|
||||
**Partial Unique Index (PostgreSQL):**
|
||||
**JSONB column:**
|
||||
```python
|
||||
from sqlalchemy.dialects import postgresql
|
||||
op.add_column('tablename', sa.Column('data', postgresql.JSONB(), nullable=True))
|
||||
```
|
||||
|
||||
**UUID FK with cascade:**
|
||||
```python
|
||||
op.add_column('tablename', sa.Column(
|
||||
'parent_id', postgresql.UUID(as_uuid=True),
|
||||
sa.ForeignKey('parents.id', ondelete='CASCADE'),
|
||||
nullable=True
|
||||
))
|
||||
```
|
||||
|
||||
**Partial unique index (PostgreSQL):**
|
||||
```python
|
||||
op.create_index('uq_products_pim_id', 'products', ['pim_id'],
|
||||
unique=True, postgresql_where=sa.text('pim_id IS NOT NULL'))
|
||||
```
|
||||
|
||||
**Enum-Wert hinzufügen (PostgreSQL-spezifisch):**
|
||||
**Add enum value (PostgreSQL):**
|
||||
```python
|
||||
op.execute("ALTER TYPE userrole ADD VALUE IF NOT EXISTS 'new_role'")
|
||||
op.execute("ALTER TYPE mediaassettype ADD VALUE IF NOT EXISTS 'usd_master'")
|
||||
```
|
||||
|
||||
**JSONB-Spalte:**
|
||||
**Rename system_settings key:**
|
||||
```python
|
||||
op.add_column('tablename', sa.Column('data', postgresql.JSONB(), nullable=True))
|
||||
op.execute("""
|
||||
UPDATE system_settings
|
||||
SET key = 'scene_linear_deflection'
|
||||
WHERE key = 'gltf_production_linear_deflection'
|
||||
""")
|
||||
```
|
||||
|
||||
**FK mit Cascade:**
|
||||
**Backfill data after adding column:**
|
||||
```python
|
||||
op.add_column('tablename', sa.Column('parent_id', postgresql.UUID(as_uuid=True),
|
||||
sa.ForeignKey('parents.id', ondelete='CASCADE'), nullable=True))
|
||||
```
|
||||
|
||||
## Backfill-Daten nach Migration
|
||||
|
||||
Wenn neue Spalten Daten aus bestehenden Rows brauchen:
|
||||
```python
|
||||
# Am Ende der upgrade()-Funktion:
|
||||
# At the end of upgrade():
|
||||
op.execute("""
|
||||
UPDATE tablename
|
||||
SET new_field = existing_field
|
||||
@@ -86,28 +95,40 @@ op.execute("""
|
||||
""")
|
||||
```
|
||||
|
||||
## Rollback bei Problemen
|
||||
## Rollback
|
||||
|
||||
```bash
|
||||
# Eine Migration zurück
|
||||
# One step back
|
||||
docker compose exec backend alembic downgrade -1
|
||||
|
||||
# Zu spezifischer Revision
|
||||
# To specific revision
|
||||
docker compose exec backend alembic downgrade [revision_id]
|
||||
```
|
||||
|
||||
## Modell-Checkliste nach Migration
|
||||
## Post-Migration Checklist
|
||||
|
||||
Nach der Migration das entsprechende SQLAlchemy-Model prüfen:
|
||||
- [ ] Neue Spalte als Python-Attribut im Model (mit korrektem Typ + `nullable`)
|
||||
- [ ] Neue Relationship mit `back_populates` auf beiden Seiten
|
||||
- [ ] Model in `backend/app/models/__init__.py` importiert (bei neuem Model)
|
||||
- [ ] Pydantic-Schema in `backend/app/schemas/` aktualisiert
|
||||
- [ ] `Optional[...]` in Schema wenn Spalte nullable
|
||||
After a successful migration, verify the corresponding SQLAlchemy model:
|
||||
- [ ] New column as Python attribute in model (correct type + `nullable`)
|
||||
- [ ] New relationship with `back_populates` on both sides
|
||||
- [ ] Model imported in `backend/app/models/__init__.py` (for new models)
|
||||
- [ ] Pydantic schema in `backend/app/domains/<domain>/schemas.py` updated
|
||||
- [ ] `Optional[...]` in schema if column is nullable
|
||||
|
||||
## Abschluss
|
||||
## Planned Migrations (from ROADMAP.md)
|
||||
|
||||
Berichte:
|
||||
- Welche Migration erstellt wurde (Dateiname + Revision-ID)
|
||||
- Was `alembic current` nach apply zeigt
|
||||
- Ob Backfill-Daten korrekt gesetzt wurden
|
||||
| Number | Description | Priority |
|
||||
|---|---|---|
|
||||
| 060 | `usd_master` enum value in `mediaassettype` | P2 |
|
||||
| 061 | `source_material_assignments`, `resolved_material_assignments`, `manual_material_overrides` JSONB on `cad_files` | P2 |
|
||||
| 062 | `render_job_doc` JSONB on `order_lines` | P7 (done as 048) |
|
||||
| 063 | Role hierarchy: `global_admin`, `tenant_admin` | P8 (done as 049) |
|
||||
| 064 | `step_hash` column on `cad_files` | P9 |
|
||||
| 065 | Rename tessellation settings keys (`gltf_production_*` → `scene_*`) | P6 |
|
||||
|
||||
## Report
|
||||
|
||||
After completing a migration, report:
|
||||
- Migration filename + revision ID
|
||||
- What `alembic current` shows after apply
|
||||
- Whether backfill data was set correctly
|
||||
- Any FK or unique constraint changes that require attention
|
||||
|
||||
Reference in New Issue
Block a user