auto-virtual-tryon-frontend/docs/superpowers/specs/2026-03-27-auto-virtual-tryon-admin-frontend-design.md

# Auto Virtual Tryon Admin Frontend Design

Date: 2026-03-27

## 1. Background

This project will be a standalone Next.js admin frontend for the virtual try-on pipeline described in the root PRD:

- PRD source: `2026-03-27-frontend-admin-prd.md`
- Backend reference: adjacent project `/Volumes/DockCase/codes/auto-virtual-tryon`

The frontend is not being designed against an abstract future system. It must respect the current backend reality.

### 1.1 Current Backend Reality

The current backend project already exposes stable APIs for:

- `POST /api/v1/orders`
- `GET /api/v1/orders/{order_id}`
- `GET /api/v1/orders/{order_id}/assets`
- `GET /api/v1/reviews/pending`
- `POST /api/v1/reviews/{order_id}/submit`
- `GET /api/v1/workflows/{order_id}`

The root PRD also describes manual revision flows and additional endpoints such as:

- `POST /api/v1/orders/{order_id}/revisions`
- `GET /api/v1/orders/{order_id}/revisions`
- `POST /api/v1/reviews/{order_id}/confirm-revision`

Those endpoints are not present in the currently implemented backend code at `/Volumes/DockCase/codes/auto-virtual-tryon/app`.

### 1.2 Design Consequence

The frontend must therefore distinguish between:

- real integration modules backed by implemented APIs
- placeholder or mock-backed modules that preserve the intended information architecture

The design does not fake backend completeness. It preserves product structure while keeping technical truth explicit.

## 2. Product Goal

Build a complete admin console shell in Next.js that:

- feels like a real internal operations product rather than a demo
- supports true end-to-end integration for the currently implemented backend workflows
- preserves the full first-phase information architecture from the PRD
- keeps future backend completion low-cost by isolating mocks and adapters away from page components

## 3. Approved Scope

### 3.1 Scope Baseline

The approved direction is:

- follow the PRD as the product baseline
- prioritize real integration pages first
- do not let the rest of the console feel unfinished or structurally hollow

### 3.2 Integration Strategy

The approved data strategy is:

- pages only request the Next.js app itself
- Next.js provides a BFF layer under `app/api/*`
- the BFF decides whether to proxy to the real FastAPI backend or return mock / placeholder data

This keeps page code unaware of whether a module is currently real or mocked.

## 4. Information Architecture

### 4.1 Primary Navigation

The first-level navigation is:

- `订单总览`
- `提单工作台`
- `审核工作台`
- `流程追踪`
- `资源库`
- `系统设置`

### 4.2 Route Structure

The approved page tree is:

- `/orders`
- `/orders/[orderId]`
- `/submit-workbench`
- `/reviews/workbench`
- `/workflows`
- `/workflows/[orderId]`
- `/libraries/models`
- `/libraries/scenes`
- `/libraries/garments`
- `/settings`
- `/login`

### 4.3 Default Entry

The default landing page remains `/orders`.

This is intentionally retained even though the backend does not yet provide a real orders list API. The page will act as the official home of the console using a transitional strategy:

- direct order lookup
- recent-visit history
- mock or placeholder overview content
- explicit messaging that full list/search depends on future backend support

## 5. Layout and Visual Direction

### 5.1 Approved Visual Direction

The approved visual direction is:

`A. Gallery-First Warm Console`

This means:

- warm neutral page background instead of pure white
- deep ink navigation shell
- restrained green accent for key CTA states
- review surfaces designed around image inspection first

### 5.2 Visual Character

The UI should feel:

- professional
- calm
- high-density but readable
- distinct from generic enterprise dashboards

It should not feel:

- cold and generic
- decorative for decoration’s sake
- overly editorial on operational pages

### 5.3 Typography and Color Rules

- Chinese UI text uses `Noto Sans SC`
- IDs, order numbers, and technical labels use `IBM Plex Mono`
- the primary accent is reserved for high-value actions such as submit and approve
- state colors are managed separately from brand accent colors
- the review workbench remains visually more restrained than marketing-style pages

## 6. Technical Architecture

### 6.1 Framework Direction

The frontend will be built as a standalone Next.js application using:

- Next.js App Router
- TypeScript
- Tailwind CSS

### 6.2 Route Grouping

The application will be organized as:

```text
app/
  (dashboard)/
    orders/page.tsx
    orders/[orderId]/page.tsx
    submit-workbench/page.tsx
    reviews/workbench/page.tsx
    workflows/page.tsx
    workflows/[orderId]/page.tsx
    libraries/models/page.tsx
    libraries/scenes/page.tsx
    libraries/garments/page.tsx
    settings/page.tsx
  login/page.tsx
  api/*
```

The dashboard route group owns the shared shell:

- side navigation
- top bar
- page content container
- shared empty states
- shared badges and status treatments

### 6.3 BFF Layer

The BFF layer under `app/api/*` is responsible for:

- request validation
- backend proxying
- response normalization
- mock response generation
- environment-based backend URL routing
- mapping backend responses into stable frontend-facing contracts

Pages do not call FastAPI directly.

## 7. Data Model Strategy

### 7.1 Frontend View Models

The UI consumes stable frontend view models rather than raw backend payloads.

Approved shared view models:

- `OrderSummaryVM`
- `OrderDetailVM`
- `ReviewQueueItemVM`
- `WorkflowDetailVM`
- `LibraryItemVM`

### 7.2 Adapter Rules

All cross-source differences are handled in adapters:

- missing backend fields are converted into explicit fallback copy or null-safe UI states
- business-empty responses are not treated as system failures
- mock asset URIs such as `mock://...` are displayed honestly as mock assets
- backend enum values are mapped once, not repeatedly in page components

### 7.3 File Decomposition

The frontend should be split along responsibility boundaries:

```text
src/
  lib/
    api/
    adapters/
    mock/
    types/
  features/
    orders/
    reviews/
    workflows/
    libraries/
  components/
    layout/
    ui/
```

The key rule is that mock-vs-real complexity must live in `lib`, not in page UI trees.

## 8. Real Modules vs Placeholder Modules

### 8.1 Real Integration Modules

The first implementation phase will perform true integration for:

- `提单工作台`
- `审核工作台`
- `订单详情`
- `流程详情页 /workflows/[orderId]`

### 8.2 Placeholder or Transitional Modules

The first implementation phase will preserve full route structure for:

- `/orders`
- `/workflows`
- `/libraries/models`
- `/libraries/scenes`
- `/libraries/garments`
- `/settings`
- `/login`

These are not “missing pages”. They are real screens with:

- proper layout
- proper states
- mock or transitional data
- explicit product messaging about current backend limitations

## 9. Core Page Responsibilities

### 9.1 `/submit-workbench`

Purpose:

- the only first-class order creation workspace

Responsibilities:

- customer level selection
- service mode selection
- mock-backed resource selection for model, scene, garment
- local validation of backend-supported combinations
- request submission to create orders
- success feedback and redirect to `/orders/[orderId]`

Non-responsibilities:

- no review actions
- no workflow timeline deep-dive
- no list monitoring behavior

### 9.2 `/reviews/workbench`

Purpose:

- the highest-frequency manual review surface

Responsibilities:

- display the pending review queue
- switch between orders quickly without route churn
- show the current candidate asset and key order context
- perform `approve` and `rerun_*` review decisions
- surface compact workflow summary and errors relevant to review

Non-responsibilities:

- not the canonical archive for full order history
- not the main workflow forensic page
- not a fake implementation of unbuilt revision-chain APIs

Because the current backend lacks revision endpoints, first implementation should present those PRD concepts as clearly marked placeholders rather than simulate unsupported actions as if they were real.

### 9.3 `/orders/[orderId]`

Purpose:

- the canonical shared order detail page

Responsibilities:

- order metadata
- current status
- asset list
- final result area
- workflow summary
- navigation to review and workflow detail pages

Non-responsibilities:

- no heavy review action UI
- no full process forensics
- no order creation

### 9.4 `/workflows/[orderId]`

Purpose:

- focused workflow inspection and troubleshooting

Responsibilities:

- workflow status card
- current step
- step timeline
- failure and anomaly details
- direct order-id-based lookup

Non-responsibilities:

- no primary image review experience
- no review decision submission
- no resource selection

## 10. UX Rules and State Handling

### 10.1 Submit Workbench Rules

- `low` must only allow `auto_basic`
- `mid` must only allow `semi_pro`
- submission failure must preserve form state
- success must show `order_id` and `workflow_id`, then redirect to order detail

### 10.2 Review Workbench Rules

- queue items are never removed optimistically on action submission
- `rerun_scene`, `rerun_face`, and `rerun_fusion` require comment input
- action failures are shown inline in the action area
- queue refresh should be explicit and predictable after successful actions

### 10.3 Order Detail Rules

- absence of final asset is a valid business state
- absence of assets is a valid business empty state
- unsupported revision-chain behavior is displayed as “not currently backed by backend” rather than as an error

### 10.4 Workflow Rules

- “not found” workflow responses must be distinguished from transport or server failures
- workflow step rendering should emphasize current step, failed step, and rerun lineage where available

## 11. Error Model

The UI uses three error/state categories:

### 11.1 Business Empty State

Examples:

- no final image yet
- no assets yet
- no real orders list yet
- no resource library backend yet

These render as valid explanatory UI states, not error banners.

### 11.2 Retryable Error

Examples:

- temporary network failure
- backend timeout
- proxy failure

These render with retry affordances.

### 11.3 System Error

Examples:

- unexpected response shape
- unrecoverable server failure
- application-level state contradiction

These render as hard failure states with diagnostic framing.

## 12. Mock and Placeholder Policy

Placeholder modules are first-class citizens in the shell, but they must remain honest.

Rules:

- never imply an unavailable backend capability is actually live
- never silently replace missing backend data with fabricated “real-looking” data on core real-integration pages
- keep mock data isolated to modules explicitly designated as transitional
- label unavailable capability clearly where it matters to task completion

## 13. Testing Strategy

First-phase testing will prioritize correctness over exhaustive visual snapshot coverage.

### 13.1 Must-Test Areas

- BFF route handlers
- adapter mapping logic
- submit workbench validation rules
- submit and review action request flows
- key page state rendering for loading, empty, success, and failure

### 13.2 Lower Priority for Phase 1

- pixel-perfect visual snapshots
- exhaustive placeholder-page snapshots
- animation-heavy testing

The purpose of the first test layer is to protect data contracts and operational flows.

## 14. Delivery Boundary

### 14.1 First-Phase Hard Acceptance

The frontend must be able to:

- create an order from the submit workbench
- review pending orders from the review workbench
- execute `approve`
- execute `rerun_scene`
- execute `rerun_face`
- execute `rerun_fusion`
- inspect order detail data
- inspect workflow detail data

### 14.2 First-Phase Structural Acceptance

The console must also provide:

- complete navigation shell
- `/orders` as the official entry page
- resource library placeholders
- workflow lookup index page
- settings and login route placeholders

## 15. Risks

- The root PRD is ahead of the currently implemented backend in revision-related capabilities.
- The default home page is structurally important but cannot yet be backed by a real list API.
- Mock asset URIs limit the realism of image preview experiences.
- Without authentication in phase 1, the console assumes a trusted environment.

## 16. Implementation Direction

The implementation should proceed by:

1. scaffolding the Next.js app shell and BFF layer
2. establishing shared types, adapters, and placeholder data contracts
3. implementing the four real-integration modules
4. filling in the transitional modules with honest placeholder behavior
5. validating the accepted states and operational flows with tests

## 17. Local Setup Notes

Implementation assumes the frontend runs with:

- `BACKEND_BASE_URL=http://127.0.0.1:8000/api/v1`

Recommended local verification commands:

- `npm run test`
- `npm run lint`
- `npm run typecheck`
- `npm run build`
- `npm run verify`

The adjacent backend project must be started separately when manually checking the four real-integration pages.