feat: connect resource library workflows

docs/superpowers/plans/2026-03-28-resource-library.md

@@ -0,0 +1,89 @@
+# Resource Library Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a real backend resource library with S3 direct-upload preparation and switch the frontend library BFF from mock data to real backend data.
+
+**Architecture:** Add a dedicated resource-library domain in the FastAPI backend with separate resource and resource-file tables. Expose presign, create, and list APIs, then proxy the list API through the Next.js BFF so the existing resource pages and submit-workbench selectors continue to work without a UI rewrite.
+
+**Tech Stack:** FastAPI, SQLAlchemy async ORM, Alembic, boto3 presigning, pytest/httpx integration tests, Next.js route handlers, Vitest
+
+---
+
+### Task 1: Backend Resource-Library Schema
+
+**Files:**
+- Create: `/Volumes/DockCase/codes/auto-virtual-tryon/app/infra/db/models/library_resource.py`
+- Create: `/Volumes/DockCase/codes/auto-virtual-tryon/app/infra/db/models/library_resource_file.py`
+- Modify: `/Volumes/DockCase/codes/auto-virtual-tryon/app/domain/enums.py`
+- Modify: `/Volumes/DockCase/codes/auto-virtual-tryon/app/infra/db/session.py`
+- Create: `/Volumes/DockCase/codes/auto-virtual-tryon/alembic/versions/20260328_0003_resource_library.py`
+- Test: `/Volumes/DockCase/codes/auto-virtual-tryon/tests/test_api.py`
+
+- [ ] **Step 1: Write the failing backend API test for creating and listing library resources**
+
+- [ ] **Step 2: Run the targeted backend test to verify it fails**
+
+- [ ] **Step 3: Add enums and ORM models for resources and resource files**
+
+- [ ] **Step 4: Add an Alembic migration for the new tables and indexes**
+
+- [ ] **Step 5: Ensure test database initialization imports the new models**
+
+- [ ] **Step 6: Run the targeted backend test again and confirm the failure moved forward from missing schema to missing API implementation**
+
+### Task 2: Backend Presign and Resource APIs
+
+**Files:**
+- Modify: `/Volumes/DockCase/codes/auto-virtual-tryon/app/config/settings.py`
+- Create: `/Volumes/DockCase/codes/auto-virtual-tryon/app/api/schemas/library.py`
+- Create: `/Volumes/DockCase/codes/auto-virtual-tryon/app/application/services/library_service.py`
+- Create: `/Volumes/DockCase/codes/auto-virtual-tryon/app/infra/storage/s3.py`
+- Create: `/Volumes/DockCase/codes/auto-virtual-tryon/app/api/routers/library.py`
+- Modify: `/Volumes/DockCase/codes/auto-virtual-tryon/app/main.py`
+- Modify: `/Volumes/DockCase/codes/auto-virtual-tryon/pyproject.toml`
+- Test: `/Volumes/DockCase/codes/auto-virtual-tryon/tests/test_api.py`
+
+- [ ] **Step 1: Write the failing backend test for presign generation**
+
+- [ ] **Step 2: Run the targeted backend presign test and verify it fails**
+
+- [ ] **Step 3: Add S3 settings and a presign helper that derives CDN public URLs**
+
+- [ ] **Step 4: Add request/response schemas for presign, create, and list APIs**
+
+- [ ] **Step 5: Implement the library service and router with one-shot create plus filtered list**
+
+- [ ] **Step 6: Run the targeted backend tests and confirm they pass**
+
+### Task 3: Frontend BFF Proxy and Mapping
+
+**Files:**
+- Modify: `/Volumes/DockCase/codes/auto-virtual-tryon-frontend/app/api/libraries/[libraryType]/route.ts`
+- Modify: `/Volumes/DockCase/codes/auto-virtual-tryon-frontend/src/lib/types/view-models.ts`
+- Create: `/Volumes/DockCase/codes/auto-virtual-tryon-frontend/src/lib/adapters/libraries.ts`
+- Modify: `/Volumes/DockCase/codes/auto-virtual-tryon-frontend/tests/app/api/libraries.route.test.ts`
+
+- [ ] **Step 1: Write the failing frontend route test for backend-proxied library data**
+
+- [ ] **Step 2: Run the targeted frontend test and verify it fails**
+
+- [ ] **Step 3: Add a backend-to-view-model adapter for library resources**
+
+- [ ] **Step 4: Replace the mock route implementation with backend proxying while preserving normalized errors**
+
+- [ ] **Step 5: Run the targeted frontend tests and confirm they pass**
+
+### Task 4: Verification
+
+**Files:**
+- Test: `/Volumes/DockCase/codes/auto-virtual-tryon/tests/test_api.py`
+- Test: `/Volumes/DockCase/codes/auto-virtual-tryon-frontend/tests/app/api/libraries.route.test.ts`
+
+- [ ] **Step 1: Run the backend targeted API tests for presign/create/list**
+
+- [ ] **Step 2: Run the frontend targeted route tests**
+
+- [ ] **Step 3: Run backend lint-equivalent checks if available, otherwise run the relevant pytest command set**
+
+- [ ] **Step 4: Run frontend `npm run typecheck` and any targeted tests affected by the library route change**

docs/superpowers/specs/2026-03-28-resource-library-design.md

@@ -0,0 +1,49 @@
+# Resource Library Design
+
+**Goal:** Build a real resource-library backend for models, scenes, and garments with S3 direct-upload preparation, persisted resource metadata, and list APIs that the existing frontend library pages can consume.
+
+**Scope:** Replace mock resource-library data with a dedicated backend resource domain. The first slice supports public-read assets, presigned upload preparation, one-shot resource creation, and real list retrieval. Upload UI is out of scope; API tests and existing frontend readers are the verification path.
+
+**Decisions**
+
+- Resource-library records are independent from order-generated assets.
+- Files are stored in S3 and read publicly through the configured CDN hostname.
+- Uploads use a two-step direct-upload flow:
+  1. Backend issues presigned upload parameters and storage metadata.
+  2. Client uploads to S3 and then creates the resource record with uploaded file metadata.
+- A resource can include:
+  - one original file
+  - one thumbnail file
+  - multiple gallery files
+- Type-specific fields in the first version:
+  - model: `gender`, `age_group`
+  - scene: `environment`
+  - garment: `category`
+- Garment category remains a plain string for now. Config management can come later.
+
+**Backend Shape**
+
+- Add a dedicated `library_resources` table for business metadata.
+- Add a dedicated `library_resource_files` table for uploaded file references.
+- Add enums for resource type, file role, and optional status/environment metadata.
+- Add API routes for:
+  - upload presign
+  - resource create
+  - resource list
+- Keep the existing order asset model untouched.
+
+**Frontend Shape**
+
+- Keep the existing frontend library pages and submit-workbench readers.
+- Replace the current mock BFF implementation with a proxy that calls the new backend list endpoint and maps backend payloads into the existing `LibraryItemVM`.
+- Upload UI is deferred. No new client-side upload forms are required in this slice.
+
+**Verification**
+
+- Backend integration tests cover:
+  - presign response generation
+  - resource creation with original/thumbnail/gallery files
+  - filtered resource listing by type and type-specific fields
+- Frontend route tests cover:
+  - successful proxying and mapping from backend payload to existing view-model shape
+  - unsupported library-type rejection remains normalized