cayden/auto-virtual-tryon-frontend

Fork 0

Files

afei A 98c6b741d6 feat: bootstrap auto virtual tryon admin frontend

2026-03-27 23:38:50 +08:00

13 KiB

Raw Permalink Blame History

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

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:

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:

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:

scaffolding the Next.js app shell and BFF layer
establishing shared types, adapters, and placeholder data contracts
implementing the four real-integration modules
filling in the transitional modules with honest placeholder behavior
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.

13 KiB Raw Permalink Blame History Unescape Escape

Auto Virtual Tryon Admin Frontend Design

1. Background

1.1 Current Backend Reality

1.2 Design Consequence

2. Product Goal

3. Approved Scope

3.1 Scope Baseline

3.2 Integration Strategy

4. Information Architecture

4.1 Primary Navigation

4.2 Route Structure

4.3 Default Entry

5. Layout and Visual Direction

5.1 Approved Visual Direction

5.2 Visual Character

5.3 Typography and Color Rules

6. Technical Architecture

6.1 Framework Direction

6.2 Route Grouping

6.3 BFF Layer

7. Data Model Strategy

7.1 Frontend View Models

7.2 Adapter Rules

7.3 File Decomposition

8. Real Modules vs Placeholder Modules

8.1 Real Integration Modules

8.2 Placeholder or Transitional Modules

9. Core Page Responsibilities

9.1 /submit-workbench

9.2 /reviews/workbench

9.3 /orders/[orderId]

9.4 /workflows/[orderId]

10. UX Rules and State Handling

10.1 Submit Workbench Rules

10.2 Review Workbench Rules

10.3 Order Detail Rules

10.4 Workflow Rules

11. Error Model

11.1 Business Empty State

11.2 Retryable Error

11.3 System Error

12. Mock and Placeholder Policy

13. Testing Strategy

13.1 Must-Test Areas

13.2 Lower Priority for Phase 1

14. Delivery Boundary

14.1 First-Phase Hard Acceptance

14.2 First-Phase Structural Acceptance

15. Risks

16. Implementation Direction

17. Local Setup Notes

13 KiB

Raw Permalink Blame History

9.1 `/submit-workbench`

9.2 `/reviews/workbench`

9.3 `/orders/[orderId]`

9.4 `/workflows/[orderId]`