duoqi-admin/CLAUDE.md

CLAUDE.md — duoqi-admin

多奇管理后台，基于 Vite + React + TypeScript + shadcn/ui + Tailwind CSS 调用 duoqi-api 的 admin 端点，CSR 纯前端应用

Current Status

Phase 1b complete. Category CRUD + Question CRUD + 知识卡编辑 + 状态流转 UI + 批量导入 all done. Next: Phase 1c.

Development follows the phased roadmap in dev-spec.md §九.

Quick Start

bun install
bun run dev          # Vite dev server, default port 5173
bun run build        # Production build → dist/

Environment

.env is already configured. To change the API URL, edit .env:

VITE_API_BASE_URL=http://localhost:3000   # duoqi-api address

Architecture

src/
├── main.tsx              # Entry point
├── App.tsx               # Root (router + layout)
├── styles/globals.css    # Tailwind v4 + shadcn/ui CSS variables
├── routes/               # Pages (login, dashboard, questions/*, categories/*, ...)
├── components/
│   ├── ui/               # shadcn/ui primitives
│   ├── layout/           # Sidebar, Header, AdminLayout
│   ├── charts/           # StatsCard, chart wrappers
│   ├── category/         # Category CRUD (columns, dialogs)
│   ├── question/         # Question CRUD (columns, form, StatusBadge, DistractorEditor, KnowledgeCardFields, StatusTransitionDialog, ImportQuestionsDialog)
├── lib/
│   ├── api-client.ts     # HTTP client for /admin/* endpoints
│   ├── auth.ts           # Admin JWT token management
│   ├── utils.ts          # Utility functions
│   └── constants.ts      # Status enums, difficulty levels
├── hooks/                # useAuth
├── stores/               # Zustand stores (auth-store)
└── types/                # question, user, category, api types

Key Patterns

• Routing: React Router v7 library mode (createBrowserRouter + RouterProvider). Routes defined in App.tsx. Root layout (routes/__root.tsx) handles auth guard — redirects to /login when not authenticated.
• Development order: Follow dev-spec.md §九 (Phase roadmap).
• Auth flow: Login page → POST /admin/auth/login with token → receive admin JWT → store in auth-store → attach as Authorization: Bearer <jwt> on all subsequent requests
• API client: All admin API calls go through lib/api-client.ts (ky v2). Uses baseUrl + prefix: "/admin". Auto-attaches auth header. 401 responses trigger logout + redirect to /login.
• Data tables: TanStack Table v8 headless + shadcn/ui styled components in components/data-table/
• Forms: React Hook Form + Zod validation for all admin forms
• State: Zustand for client state only; server state fetched via API client

Gotchas

• shadcn/ui CLI: After bunx shadcn@latest add ..., verify files land in src/components/ui/ — sometimes they end up in @/components/ui/ at project root instead.
• ky v2: Uses baseUrl + prefix (not prefixUrl). Hooks receive a single state object ({ request }, { response }) instead of positional arguments.
• TypeScript 6: Requires "ignoreDeprecations": "6.0" in tsconfig when using baseUrl + paths for @/* aliases.
• Tailwind v4: Uses @import "tailwindcss" and @theme inline block (not @tailwind base/components/utilities).
• Zod v4: Import from zod/v4 (not zod). Use @hookform/resolvers/zod for form resolver.
• TypeScript verbatimModuleSyntax: All type-only imports must use import type syntax. Common: ColumnDef from TanStack Table, UseFormRegister from react-hook-form, z.infer results.
• react-hook-form sub-components: UseFormRegister<A> is not assignable to UseFormRegister<B> even when A extends B (contravariance). Prefer inlining fields or passing individual register("field") results as props.

Design Docs

Doc	Path	Notes
Dev spec (primary)	./dev-spec.md	Full engineering spec — read before development
Product overview	../docs/product-overview.md	Product scope, phases
Tech stack	../docs/tech-stack.md	Full-stack decisions
duoqi-api spec	../docs/specs/duoqi-api/dev-spec.md	Admin API endpoint definitions
Question format	../docs/specs/shared/question-format-design.md	Question data model (core for CRUD)
Gamification	../docs/specs/shared/gamification-monetization-design.md	Skill tree, subscription tiers
Analytics	../docs/specs/shared/analytics-feedback-design.md	Stats metrics, feedback data

技术栈速查

• 框架：Vite + React 18
• 语言：TypeScript
• UI：shadcn/ui + Tailwind CSS
• 数据表格：TanStack Table v8
• 表单：React Hook Form + Zod
• 图表：Recharts
• HTTP：ky v2
• 状态：Zustand
• 路由：React Router v7
• 包管理：bun