# CLAUDE.md — duoqi-admin

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

## Current Status

**Pre-implementation.** Only `CLAUDE.md` and `dev-spec.md` exist. No source code, no `package.json`, no `src/` directory yet.

Development follows the phased roadmap in [dev-spec.md](./dev-spec.md) §九:
- Phase 1a: Project scaffold (Vite + React + TS + Tailwind + shadcn/ui + routing + auth + login page)
- Phase 1b: Question CRUD core
- Phase 1c: Skill tree, dashboard data, batch operations

Start with Phase 1a — initialize the project before building features.

## Quick Start

> These commands will work after Phase 1a project initialization.

```bash
bun install
bun run dev          # Vite dev server, default port 5173
bun run build        # Production build → dist/
bun run preview      # Preview production build locally
```

## Environment

Copy `.env.example` to `.env`:

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

## Architecture

> **Note:** The structure below is the *target* architecture from `dev-spec.md`.
> Actual files will be created during Phase 1a implementation.

```
src/
├── main.tsx              # Entry point
├── App.tsx               # Root (router + layout)
├── routes/               # File-based pages (login, questions/*, categories/*, ...)
├── components/
│   ├── ui/               # shadcn/ui primitives
│   ├── layout/           # Sidebar, Header, AdminLayout
│   ├── data-table/       # DataTable (TanStack Table wrapper)
│   ├── question-form/    # Question editing form
│   └── charts/           # Recharts wrappers
├── 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, usePagination
├── stores/               # Zustand stores (auth-store)
└── types/                # question, user, category, api types
```

## Key Patterns

- **Development order**: Follow [dev-spec.md](./dev-spec.md) §九 (Phase roadmap). Phase 1a is the scaffold — init project, configure shadcn/ui, set up routing, API client, auth, login page, dashboard skeleton.
- **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`, base URL from `VITE_API_BASE_URL`, auto-attaches auth header
- **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

## Design Docs

| Doc | Path | Notes |
|-----|------|-------|
| **Dev spec (primary)** | [./dev-spec.md](./dev-spec.md) | Full engineering spec — read before development |
| Product overview | [../docs/product-overview.md](../docs/product-overview.md) | Product scope, phases |
| Tech stack | [../docs/tech-stack.md](../docs/tech-stack.md) | Full-stack decisions |
| duoqi-api spec | [../docs/specs/duoqi-api/dev-spec.md](../docs/specs/duoqi-api/dev-spec.md) | Admin API endpoint definitions |
| Question format | [../docs/specs/shared/question-format-design.md](../docs/specs/shared/question-format-design.md) | Question data model (core for CRUD) |
| Gamification | [../docs/specs/shared/gamification-monetization-design.md](../docs/specs/shared/gamification-monetization-design.md) | Skill tree, subscription tiers |
| Analytics | [../docs/specs/shared/analytics-feedback-design.md](../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 / fetch
- 状态：Zustand
- 路由：React Router v7
- 包管理：bun