From 23e0438f2c2ed3b9150df66049f94016e64c6dca Mon Sep 17 00:00:00 2001
From: Wang Zhuoxuan <wangzhuoxuan210@gmail.com>
Date: Tue, 7 Apr 2026 10:53:28 +0800
Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20CLAUDE.md=EF=BC=9A?=
 =?UTF-8?q?=E5=8F=8D=E6=98=A0=20Phase=201a=20=E5=AE=8C=E6=88=90=E7=8A=B6?=
 =?UTF-8?q?=E6=80=81=EF=BC=8C=E8=A1=A5=E5=85=85=E5=BA=93=E7=89=88=E6=9C=AC?=
 =?UTF-8?q?=E6=B3=A8=E6=84=8F=E4=BA=8B=E9=A1=B9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 更新项目状态为 Phase 1a 完成
- 补充实际目录结构（含 styles/globals.css）
- 新增 Key Patterns：路由配置、API 客户端细节
- 新增 Gotchas：shadcn/ui CLI 路径、ky v2 API、TS6、Tailwind v4
- 移除过时的"Pre-implementation"描述
---
 CLAUDE.md | 42 ++++++++++++++++++++----------------------
 1 file changed, 20 insertions(+), 22 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 84f1805..729d489 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -5,29 +5,21 @@
 
 ## Current Status
 
-**Pre-implementation.** Only `CLAUDE.md` and `dev-spec.md` exist. No source code, no `package.json`, no `src/` directory yet.
+**Phase 1a complete.** Project scaffold built. Phase 1b (Question CRUD) is next.
 
-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.
+Development follows the phased roadmap in [dev-spec.md](./dev-spec.md) §九.
 
 ## 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` is already configured. To change the API URL, edit `.env`:
 
 ```env
 VITE_API_BASE_URL=http://localhost:3000   # duoqi-api address
@@ -35,39 +27,45 @@ 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/*, ...)
+├── styles/globals.css    # Tailwind v4 + shadcn/ui CSS variables
+├── routes/               # Pages (login, dashboard, 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
+│   ├── charts/           # StatsCard, chart wrappers
+│   └── data-table/       # (Phase 1b) DataTable
+│   └── question-form/    # (Phase 1b) Question editing form
 ├── 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
+├── hooks/                # useAuth
 ├── 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.
+- **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](./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`, base URL from `VITE_API_BASE_URL`, auto-attaches auth header
+- **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`).
+
 ## Design Docs
 
 | Doc | Path | Notes |
@@ -88,7 +86,7 @@ src/
 - 数据表格：TanStack Table v8
 - 表单：React Hook Form + Zod
 - 图表：Recharts
-- HTTP：ky / fetch
+- HTTP：ky v2
 - 状态：Zustand
 - 路由：React Router v7
 - 包管理：bun