更新 CLAUDE.md：反映 Phase 1a 完成状态，补充库版本注意事项
- 更新项目状态为 Phase 1a 完成 - 补充实际目录结构（含 styles/globals.css） - 新增 Key Patterns：路由配置、API 客户端细节 - 新增 Gotchas：shadcn/ui CLI 路径、ky v2 API、TS6、Tailwind v4 - 移除过时的"Pre-implementation"描述
This commit is contained in:
parent
ccc32538a1
commit
23e0438f2c
42
CLAUDE.md
42
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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user