HartOMat/plan.md

Plan: P2 USD Foundation — Commit & Verify

Context

All five P2 milestones are already implemented in the working tree as uncommitted changes. The task now is to apply the DB migrations, commit the work, and verify the stack runs.

Milestone status (assessed 2026-03-12)

Milestone	Status	Key files
M1: export_step_to_usd.py with schaeffler:partKey	✅ DONE	render-worker/scripts/export_step_to_usd.py (631 lines)
M2: usd_master MediaAsset + migrations 060–062 + Celery task	✅ DONE	migrations 060/061/062, generate_usd_master_task in export_glb.py
M3: GET /api/cad/{id}/scene-manifest	✅ DONE	part_key_service.py, SceneManifest schema, endpoint in cad.py
M4: PUT /api/cad/{id}/manual-material-overrides	✅ DONE	New endpoint pair in cad.py, saveManualOverrides in cad.ts
M5: ThreeDViewer uses partKey, survives reload	✅ DONE	partKeyMap in GLB extras, effectiveMaterials merge, server-side persistence

Affected Files (all uncommitted — working tree only)

Backend

• backend/alembic/versions/060_usd_master_asset_type.py — new migration
• backend/alembic/versions/061_material_assignment_layers.py — new migration
• backend/alembic/versions/062_rename_tessellation_settings.py — new migration
• backend/app/domains/media/models.py — MediaAssetType.usd_master added
• backend/app/domains/products/models.py — 3 new JSONB columns on CadFile
• backend/app/domains/products/schemas.py — SceneManifest, PartEntry Pydantic models
• backend/app/domains/pipeline/tasks/export_glb.py — generate_usd_master_task + auto-chain
• backend/app/domains/pipeline/tasks/extract_metadata.py — minor update
• backend/app/domains/pipeline/tasks/render_thumbnail.py — minor update
• backend/app/domains/pipeline/tasks/render_order_line.py — minor update
• backend/app/api/routers/cad.py — scene-manifest + manual-material-overrides endpoints
• backend/app/api/routers/admin.py — generate-missing-usd-masters + generate-missing-canonical-scenes buttons
• backend/app/services/part_key_service.py — new file: build_scene_manifest(), generate_part_key()
• backend/app/core/config_service.py — minor update
• backend/app/core/tenant_context.py — new file
• backend/app/tasks/step_tasks.py — re-exports generate_usd_master_task

Render worker

• render-worker/scripts/export_step_to_usd.py — new file: full USD exporter
• render-worker/scripts/export_step_to_gltf.py — injects partKeyMap into GLB extras
• render-worker/scripts/still_render.py — USD path support
• render-worker/scripts/turntable_render.py — USD path support
• render-worker/Dockerfile — usd-core>=24.11 added

Frontend

• frontend/src/api/cad.ts — getManualOverrides(), saveManualOverrides()
• frontend/src/api/media.ts — usd_master type added
• frontend/src/api/sceneManifest.ts — new file: SceneManifest, fetchSceneManifest()
• frontend/src/components/cad/ThreeDViewer.tsx — partKeyMap, effectiveMaterials, reconciliation panel
• frontend/src/components/cad/MaterialPanel.tsx — dual-path save, provenance badge
• frontend/src/pages/Admin.tsx — USD master bulk action buttons
• frontend/src/pages/ProductDetail.tsx — usd_master row in asset table
• frontend/src/pages/Orders.tsx — minor update

Tasks (in order)

[ ] Task 1: Apply migrations 060–062

• What: Run docker compose exec backend alembic upgrade head to apply the three pending migrations
• Acceptance gate: docker compose exec backend alembic current shows 062 (or higher) as current
• Dependencies: none
• Risk: Low — each migration is additive (ADD VALUE, ADD COLUMN, UPDATE). Check for phantom drops before running.

[ ] Task 2: TypeScript check

• What: Run docker compose exec frontend npx tsc --noEmit to verify no type errors in the frontend changes
• Acceptance gate: Zero TypeScript errors
• Dependencies: none (frontend hot-reload, no rebuild needed)
• Risk: Low

[ ] Task 3: Rebuild and restart backend + render-worker

• What: docker compose up -d --build backend worker render-worker beat — picks up new Dockerfile (usd-core), new tasks, and new migrations
• Acceptance gate: docker compose logs backend | grep "Application startup complete" and docker compose exec render-worker python3 -c "from pxr import Usd; print(Usd.GetVersion())" both succeed
• Dependencies: Task 1
• Risk: Medium — usd-core pip install adds build time; if it fails the render-worker won't start

[ ] Task 4: Commit all P2 work

• What: Stage and commit all uncommitted P2 files in a single feat(P2) commit
• Acceptance gate: git status shows clean working tree (except LEARNINGS.md and review-report.md which can be included)
• Dependencies: Tasks 1–3 (verify before committing)
• Risk: Low

[ ] Task 5: Smoke-test end-to-end via Admin panel

• What: Via Admin → "Generate Missing Canonical Scenes" to regenerate GLBs with partKeyMap + auto-chain USD masters for existing CAD files
• Acceptance gate:
  • GET /api/cad/{id}/scene-manifest returns {"parts": [...], ...} for a processed CadFile
  • ThreeDViewer loads, click a part → MaterialPanel shows assignment provenance
  • Assign a material → reload page → assignment still present
• Dependencies: Task 3
• Risk: Medium — existing CAD files need backfill; may take minutes for bulk jobs to complete

Migration Check

Three migrations are pending in the working tree:

• 060_usd_master_asset_type.py — additive enum value
• 061_material_assignment_layers.py — additive JSONB columns
• 062_rename_tessellation_settings.py — UPDATE on system_settings rows (already checked: migration 062 was applied per review-report)

Before running: read each migration file to confirm no unexpected DROP statements.

Order Recommendation

Migrations → TypeScript check → Rebuild → Commit → Smoke test

Risks / Open Questions

• usd-core build in Docker may be slow (first build) — expected, not a problem
• Migration 062 may already be applied (review noted "verified by 0-row SELECT") — alembic upgrade head is idempotent if so
• Existing CAD files need backfill for partKeyMap in GLB extras — handled by "Generate Missing Canonical Scenes" bulk action
• resolvePartKey() falls back to identity (raw mesh name) for GLBs generated before this change — graceful degradation, not a blocking issue