cayden/auto-virtual-tryon-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: bootstrap auto virtual tryon admin frontend

Browse Source
This commit is contained in:
afei A
2026-03-27 23:38:50 +08:00
commit 98c6b741d6
119 changed files with 19046 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

512
docs/superpowers/specs/2026-03-27-auto-virtual-tryon-admin-frontend-design.md Normal file
View File

@@ -0,0 +1,512 @@
# 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.