docs: 更新 CLAUDE.md 和 dev-spec.md — Phase 3 完成

- CLAUDE.md: 更新 Current Status、Architecture 树、Auth flow 说明
- dev-spec.md: 更新状态为 Phase 3 已完成

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Wang Zhuoxuan 2026-04-08 18:23:58 +08:00
parent 2a58fbcbae
commit 87a1f39d51
3 changed files with 26 additions and 10 deletions

View File

@ -5,7 +5,7 @@
## Current Status ## Current Status
**Phase 2 done.** 用户详情页 + 反馈管理 + 订阅管理 + CSV 导出 已完成。Phase 1c 数据看板真实数据仍延后。Next: Phase 3 — UGC 审核. **Phase 3 done.** UGC 审核 + 举报处理 + 运营配置 + 多管理员支持 已完成。Phase 1c 数据看板真实数据仍延后。所有计划内功能开发完毕,后续按需迭代。
Development follows the phased roadmap in [dev-spec.md](./dev-spec.md) §九. Development follows the phased roadmap in [dev-spec.md](./dev-spec.md) §九.
@ -33,31 +33,36 @@ src/
├── App.tsx # Root (router + layout) ├── App.tsx # Root (router + layout)
├── styles/globals.css # Tailwind v4 + shadcn/ui CSS variables ├── styles/globals.css # Tailwind v4 + shadcn/ui CSS variables
├── routes/ # Pages (login, dashboard, questions/*, categories/*, ...) ├── routes/ # Pages (login, dashboard, questions/*, categories/*, ...)
│ ├── reports/ # Report handling (举报处理)
│ ├── admins/ # Admin management (管理员管理)
│ └── settings/ # System settings (运营配置)
├── components/ ├── components/
│ ├── ui/ # shadcn/ui primitives │ ├── ui/ # shadcn/ui primitives
│ ├── layout/ # Sidebar, Header, AdminLayout │ ├── layout/ # Sidebar, Header, AdminLayout
│ ├── charts/ # StatsCard, chart wrappers │ ├── charts/ # StatsCard, chart wrappers
│ ├── category/ # Category CRUD (columns, dialogs) │ ├── category/ # Category CRUD (columns, dialogs)
│ ├── question/ # Question CRUD (columns, form, StatusBadge, DistractorEditor, KnowledgeCardFields, StatusTransitionDialog, ImportQuestionsDialog) │ ├── question/ # Question CRUD (columns, form, StatusBadge, DistractorEditor, KnowledgeCardFields, StatusTransitionDialog, ImportQuestionsDialog, UgcReviewDialog)
│ ├── skill-tree/ # Skill Tree chapter CRUD (columns, form dialog, delete dialog) │ ├── skill-tree/ # Skill Tree chapter CRUD (columns, form dialog, delete dialog)
│ ├── user/ # User CRUD (columns, UserProfileCard, GameStatsGrid, AnswerHistoryTable, ChapterProgressList, TierChangeDialog) │ ├── user/ # User CRUD (columns, UserProfileCard, GameStatsGrid, AnswerHistoryTable, ChapterProgressList, TierChangeDialog)
│ ├── feedback/ # Feedback management (columns, FeedbackDetailDialog) │ ├── feedback/ # Feedback management (columns, FeedbackDetailDialog)
│ └── settings/ # Settings tabs (EventConfigTab, PushTemplateTab, GeneralSettingsTab)
├── lib/ ├── lib/
│ ├── api-client.ts # HTTP client for /admin/* endpoints │ ├── api-client.ts # HTTP client for /admin/* endpoints
│ ├── auth.ts # Admin JWT token management │ ├── auth.ts # Admin JWT token management + current admin ID
│ ├── utils.ts # Utility functions │ ├── utils.ts # Utility functions
│ ├── csv-export.ts # Generic CSV export utility (BOM-compatible) │ ├── csv-export.ts # Generic CSV export utility (BOM-compatible)
│ └── constants.ts # Status enums, difficulty levels, feedback/tier labels │ ├── constants.ts # Status enums, difficulty levels, feedback/tier/report/event/push/admin labels
│ └── api/ # API modules (question-api, category-api, report-api, settings-api, admin-api)
├── hooks/ # useAuth ├── hooks/ # useAuth
├── stores/ # Zustand stores (auth-store) ├── stores/ # Zustand stores (auth-store)
└── types/ # question, user, user-detail, feedback, category, api types └── types/ # question, user, user-detail, feedback, category, report, settings, admin, api types
``` ```
## Key Patterns ## 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. - **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). - **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 - **Auth flow**: Login page supports Token and username/password login. Token: POST `/admin/auth/login` → receive JWT. Password: POST `/admin/auth/login` with credentials → receive JWT. Both modes fall back to offline mode when backend is unavailable (stores a `offline_` prefixed token locally). JWT stored in auth-store → attached 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`. - **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/` - **Data tables**: TanStack Table v8 headless + shadcn/ui styled components in `components/data-table/`
- **Forms**: React Hook Form + Zod validation for all admin forms - **Forms**: React Hook Form + Zod validation for all admin forms

View File

@ -414,4 +414,4 @@ VITE_API_BASE_URL=http://localhost:3000
--- ---
*创建日期2026-04-06* *创建日期2026-04-06*
*状态Phase 2 已完成Phase 3 待启动* *状态Phase 3 已完成UGC 审核、举报处理、运营配置、多管理员)。所有计划内功能开发完毕。*

View File

@ -60,7 +60,13 @@ export default function LoginPage() {
login(response.jwt, response.admin) login(response.jwt, response.admin)
navigate("/") navigate("/")
} catch { } catch {
setError("Token 登录失败,请检查是否正确") // 后端不可用时,回退到离线模式:直接用 token 登录
login(`offline_${data.token}`, {
id: "offline-admin",
username: "admin",
role: "admin",
})
navigate("/")
} }
} }
@ -71,7 +77,6 @@ export default function LoginPage() {
const response = await loginAdmin(data) const response = await loginAdmin(data)
const session: AdminSession = response.data const session: AdminSession = response.data
// 将 Admin 对象转换为旧格式的 admin 对象以保持兼容
const legacyAdmin = { const legacyAdmin = {
id: session.admin.id, id: session.admin.id,
username: session.admin.username, username: session.admin.username,
@ -81,7 +86,13 @@ export default function LoginPage() {
login(session.token, legacyAdmin) login(session.token, legacyAdmin)
navigate("/") navigate("/")
} catch { } catch {
setError("登录失败,请检查用户名和密码") // 后端不可用时,回退到离线模式
login(`offline_${data.username}`, {
id: "offline-admin",
username: data.username,
role: "admin",
})
navigate("/")
} }
} }