diff --git a/docs/superpowers/plans/2026-03-28-auto-virtual-tryon-admin-frontend-shadcn-rewrite.md b/docs/superpowers/plans/2026-03-28-auto-virtual-tryon-admin-frontend-shadcn-rewrite.md new file mode 100644 index 0000000..1fed7c2 --- /dev/null +++ b/docs/superpowers/plans/2026-03-28-auto-virtual-tryon-admin-frontend-shadcn-rewrite.md @@ -0,0 +1,459 @@ +# Auto Virtual Tryon Admin Frontend Shadcn Rewrite 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:** Rebuild the frontend admin UI around a denser shadcn-style console shell, a clearer review workflow, and real high-density list pages for orders and workflows. + +**Architecture:** Keep the existing App Router routes, BFF handlers, adapters, and backend contracts intact while replacing the card-heavy presentation layer with shared shell, toolbar, and table primitives. Migrate in layers: first the dashboard shell and reusable UI primitives, then the review flow, then the orders and workflows list pages, so each step lands on top of a stable layout system instead of reworking page code twice. + +**Tech Stack:** Next.js App Router, React, TypeScript, Tailwind CSS v4, Vitest, React Testing Library, jsdom, Lucide React + +--- + +### Task 1: Rebuild The Shared Dashboard Shell + +**Files:** +- Modify: `src/components/layout/dashboard-shell.tsx` +- Modify: `src/components/layout/nav-config.ts` +- Modify: `src/components/ui/page-header.tsx` +- Modify: `app/globals.css` +- Test: `tests/ui/dashboard-shell.test.tsx` + +- [ ] **Step 1: Write the failing shell-density tests** + +```tsx +test("uses a narrow rail and full-width desktop shell", () => { + render(content); + + expect(screen.getByLabelText("Dashboard rail").className).toContain( + "md:w-[228px]", + ); + expect(screen.getByLabelText("Dashboard content").className).toContain( + "md:overflow-y-auto", + ); +}); +``` + +- [ ] **Step 2: Run the shell test to confirm it fails** + +Run: `npm run test -- tests/ui/dashboard-shell.test.tsx` +Expected: FAIL because the existing shell still uses the wide `280px` rail, large radii, and old container classes + +- [ ] **Step 3: Rewrite the shell layout to use a thinner rail and full-width main area** + +```tsx +
+
+
+
+``` + +- [ ] **Step 4: Tighten the shared header spacing and typography** + +```tsx +
+
+

+ {eyebrow} +

+

{title}

+
+
+``` + +- [ ] **Step 5: Update shell variables and density tokens in global CSS** + +```css +:root { + --page-gap: 16px; + --panel-radius: 14px; + --control-height: 38px; +} +``` + +- [ ] **Step 6: Re-run the shell test** + +Run: `npm run test -- tests/ui/dashboard-shell.test.tsx` +Expected: PASS + +- [ ] **Step 7: Commit the shell rewrite** + +```bash +git add src/components/layout/dashboard-shell.tsx src/components/layout/nav-config.ts src/components/ui/page-header.tsx app/globals.css tests/ui/dashboard-shell.test.tsx +git commit -m "feat: tighten dashboard shell density" +``` + +### Task 2: Add Shared Dense Console Primitives + +**Files:** +- Create: `src/components/ui/input.tsx` +- Create: `src/components/ui/select.tsx` +- Create: `src/components/ui/table.tsx` +- Create: `src/components/ui/separator.tsx` +- Create: `src/components/ui/page-toolbar.tsx` +- Create: `src/components/ui/metric-chip.tsx` +- Modify: `src/components/ui/button.tsx` +- Modify: `src/components/ui/card.tsx` +- Modify: `src/components/ui/status-badge.tsx` +- Test: `tests/ui/status-badge.test.tsx` +- Create: `tests/ui/page-toolbar.test.tsx` + +- [ ] **Step 1: Write failing tests for compact toolbar and compact badge behavior** + +```tsx +test("renders a dense toolbar row with compact controls", () => { + render( + + + + + + +``` + +- [ ] **Step 4: Rebuild the queue body as a compact table** + +```tsx + + + + 订单号 + workflowId + 当前状态 + 当前步骤 + 修订状态 + 失败次数 + 更新时间 + 操作 + + +
+``` + +- [ ] **Step 5: Re-run the review queue test** + +Run: `npm run test -- tests/features/reviews/review-workbench-list.test.tsx` +Expected: PASS + +- [ ] **Step 6: Commit the queue rewrite** + +```bash +git add src/features/reviews app/\(dashboard\)/reviews/workbench/page.tsx tests/features/reviews/review-workbench-list.test.tsx +git commit -m "feat: rewrite review queue as dense table" +``` + +### Task 4: Rewrite The Review Detail Page As A Decision Surface + +**Files:** +- Modify: `src/features/reviews/review-workbench-detail.tsx` +- Modify: `src/features/reviews/components/review-action-panel.tsx` +- Modify: `src/features/reviews/components/review-image-panel.tsx` +- Modify: `src/features/reviews/components/review-revision-panel.tsx` +- Modify: `src/features/reviews/components/review-workflow-summary.tsx` +- Modify: `app/(dashboard)/reviews/workbench/[orderId]/page.tsx` +- Test: `tests/features/reviews/review-workbench-detail.test.tsx` + +- [ ] **Step 1: Rewrite the detail-page tests around sticky summary and two-column decision layout** + +```tsx +test("keeps the decision actions visible next to the image workspace", async () => { + render(); + + expect(await screen.findByText("返回审核列表")).toBeInTheDocument(); + expect(screen.getByText("审核动作")).toBeInTheDocument(); + expect(screen.getByText("人工修订")).toBeInTheDocument(); +}); +``` + +- [ ] **Step 2: Run the review detail test to confirm it fails** + +Run: `npm run test -- tests/features/reviews/review-workbench-detail.test.tsx` +Expected: FAIL because the current detail page still renders the old header and stacked module layout + +- [ ] **Step 3: Add the sticky summary bar and two-column page frame** + +```tsx +
+
+ +
+
+``` + +- [ ] **Step 4: Collapse workflow timeline content into a compact summary block and keep primary actions grouped** + +```tsx + + + 审核动作 + 人工修订 + + +``` + +- [ ] **Step 5: Re-run the review detail test** + +Run: `npm run test -- tests/features/reviews/review-workbench-detail.test.tsx` +Expected: PASS + +- [ ] **Step 6: Commit the review detail rewrite** + +```bash +git add src/features/reviews app/\(dashboard\)/reviews/workbench/\[orderId\]/page.tsx tests/features/reviews/review-workbench-detail.test.tsx +git commit -m "feat: rebuild review detail decision surface" +``` + +### Task 5: Rewrite Orders As A Real Dense List Page + +**Files:** +- Modify: `src/features/orders/orders-home.tsx` +- Create: `src/features/orders/components/orders-toolbar.tsx` +- Create: `src/features/orders/components/orders-table.tsx` +- Modify: `app/(dashboard)/orders/page.tsx` +- Test: `tests/features/orders/orders-home.test.tsx` + +- [ ] **Step 1: Replace the current orders-home expectations with dense-table expectations** + +```tsx +test("renders orders as a high-density table with shared toolbar controls", async () => { + render(); + + expect(screen.getByRole("columnheader", { name: "订单号" })).toBeInTheDocument(); + expect(screen.getByRole("columnheader", { name: "服务模式" })).toBeInTheDocument(); + expect(screen.getByLabelText("订单状态筛选")).toBeInTheDocument(); +}); +``` + +- [ ] **Step 2: Run the orders-home test to confirm it fails** + +Run: `npm run test -- tests/features/orders/orders-home.test.tsx` +Expected: FAIL because the current page still renders direct-lookup and recent-visits cards rather than a dense list table + +- [ ] **Step 3: Extract the compact toolbar with keyword, status, service mode, and pagination controls** + +```tsx + +``` + +- [ ] **Step 4: Replace the card list with a real orders table and compact row actions** + +```tsx + +``` + +- [ ] **Step 5: Re-run the orders-home test** + +Run: `npm run test -- tests/features/orders/orders-home.test.tsx` +Expected: PASS + +- [ ] **Step 6: Commit the orders page rewrite** + +```bash +git add src/features/orders app/\(dashboard\)/orders/page.tsx tests/features/orders/orders-home.test.tsx +git commit -m "feat: rewrite orders page as dense list" +``` + +### Task 6: Rewrite Workflows As A Real Dense List Page + +**Files:** +- Modify: `src/features/workflows/workflow-lookup.tsx` +- Create: `src/features/workflows/components/workflow-toolbar.tsx` +- Create: `src/features/workflows/components/workflow-table.tsx` +- Modify: `app/(dashboard)/workflows/page.tsx` +- Test: `tests/features/workflows/workflow-lookup.test.tsx` + +- [ ] **Step 1: Replace the current workflow-page expectations with dense-table expectations** + +```tsx +test("renders workflows as a high-density table with shared toolbar controls", async () => { + render(); + + expect(screen.getByRole("columnheader", { name: "流程类型" })).toBeInTheDocument(); + expect(screen.getByRole("columnheader", { name: "失败次数" })).toBeInTheDocument(); + expect(screen.getByLabelText("流程状态筛选")).toBeInTheDocument(); +}); +``` + +- [ ] **Step 2: Run the workflow-page test to confirm it fails** + +Run: `npm run test -- tests/features/workflows/workflow-lookup.test.tsx` +Expected: FAIL because the current page still renders direct-lookup and placeholder index cards rather than a dense table + +- [ ] **Step 3: Extract the compact workflow toolbar** + +```tsx + +``` + +- [ ] **Step 4: Replace the workflow card list with a diagnostic table** + +```tsx + +``` + +- [ ] **Step 5: Re-run the workflow-page test** + +Run: `npm run test -- tests/features/workflows/workflow-lookup.test.tsx` +Expected: PASS + +- [ ] **Step 6: Commit the workflows page rewrite** + +```bash +git add src/features/workflows app/\(dashboard\)/workflows/page.tsx tests/features/workflows/workflow-lookup.test.tsx +git commit -m "feat: rewrite workflows page as dense list" +``` + +### Task 7: Clean Up Old Oversized Patterns And Verify The Whole Rewrite + +**Files:** +- Modify: `src/features/orders/components/order-summary-card.tsx` +- Modify: `src/features/orders/components/order-workflow-card.tsx` +- Modify: `src/features/workflows/components/workflow-status-card.tsx` +- Modify: `src/features/workflows/components/workflow-timeline.tsx` +- Modify: `README.md` +- Test: `tests/features/orders/order-detail.test.tsx` +- Test: `tests/features/workflows/workflow-detail.test.tsx` + +- [ ] **Step 1: Write or adjust any failing detail-page tests caused by the density-system changes** + +```tsx +test("keeps order detail summaries compact under the new density rules", () => { + render(); + + expect(screen.getByText("订单摘要")).toBeInTheDocument(); +}); +``` + +- [ ] **Step 2: Run the affected detail tests to confirm what regressed** + +Run: `npm run test -- tests/features/orders/order-detail.test.tsx tests/features/workflows/workflow-detail.test.tsx` +Expected: FAIL only if the shared primitive changes require updated structure or copy assertions + +- [ ] **Step 3: Remove any leftover oversized radii, padding, and stacked-card patterns from detail support components** + +```tsx +
+ ... +
+``` + +- [ ] **Step 4: Update the README to mention the shadcn-style dense console direction** + +```md +- shared admin shell uses compact toolbar and table patterns +- review, orders, and workflows pages are optimized for desktop operator density +``` + +- [ ] **Step 5: Run full verification** + +Run: `npm run verify` +Expected: PASS with all Vitest suites green, ESLint green, TypeScript green, and `next build` green + +- [ ] **Step 6: Run a browser smoke test on the three main surfaces** + +Run: `npm run dev` +Expected: desktop manual check confirms wider shell, denser lists, and clearer review flow on `/orders`, `/reviews/workbench`, `/workflows` + +- [ ] **Step 7: Commit the cleanup and verification pass** + +```bash +git add src/features/orders/components src/features/workflows/components README.md +git commit -m "refactor: align detail views with dense console ui" +```