mzaxdandClaude
a0cca1f171
- 添加开发命令参考（构建、测试、数据库） - 新增架构概述章节（i18n、App Router、数据库等） - 完善 MCP Servers 使用说明 - 统一提交信息格式规范 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
93 lines
3.6 KiB
Markdown
93 lines
3.6 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Development Commands
|
||
|
||
### Build & Run
|
||
```bash
|
||
pnpm dev # Start development server (Next.js 15)
|
||
pnpm build # Build for production
|
||
pnpm start # Start production server
|
||
pnpm lint # Run ESLint
|
||
```
|
||
|
||
### Testing
|
||
```bash
|
||
pnpm test # Run Vitest unit tests
|
||
pnpm test:e2e # Run Playwright E2E tests
|
||
```
|
||
|
||
### Database
|
||
```bash
|
||
pnpm prisma migrate dev # Run database migrations
|
||
pnpm prisma migrate dev --name init # Create initial migration
|
||
pnpm prisma db seed # Seed database (uses ts-node)
|
||
pnpm prisma studio # Open Prisma Studio for database inspection
|
||
```
|
||
|
||
## Architecture Overview
|
||
|
||
This is a **Next.js 15 multilingual AI project navigation website** using the App Router architecture with the following key components:
|
||
|
||
### i18n Architecture (next-intl)
|
||
- **Locales**: `zh` (default) and `en`
|
||
- **Route pattern**: `/{locale}/path` (always prefixed with locale)
|
||
- **Middleware**: `src/middleware.ts` handles locale detection and routing
|
||
- **i18n config**: `src/i18n/request.ts` loads locale messages from `src/messages/{locale}.json`
|
||
- **Messages**: Translation files at `src/messages/zh.json` and `src/messages/en.json`
|
||
|
||
### App Router Structure
|
||
```
|
||
src/app/
|
||
├── [locale]/ # Locale-scoped routes
|
||
│ ├── page.tsx # Home page
|
||
│ ├── projects/ # Projects listing
|
||
│ └── layout.tsx # Locale layout (header, footer)
|
||
├── api/ # API routes (no locale prefix)
|
||
│ └── webhook/projects/route.ts # Webhook for project ingestion
|
||
└── layout.tsx # Root layout
|
||
```
|
||
|
||
### Database (Prisma + PostgreSQL)
|
||
- **Schema**: `prisma/schema.prisma` defines models: `Project`, `Tag`, `ExternalLink`
|
||
- **Enums**: `ProjectStatus` (ACTIVE/ARCHIVED), `LinkType` (WEBSITE/GITHUB/HUGGINGFACE/PAPER)
|
||
- **Client singleton**: `src/lib/prisma.ts` exports Prisma client instance
|
||
- **Multilingual fields**: Most models have `name`/`nameEn`, `description`/`descriptionEn` pairs
|
||
|
||
### Webhook Deduplication Strategy
|
||
The webhook at `src/app/api/webhook/projects/route.ts` implements a **multi-level deduplication** strategy to prevent duplicate projects:
|
||
1. **GitHub URL exact match** (highest priority)
|
||
2. **Website URL exact match**
|
||
3. **slug match** (fallback)
|
||
|
||
### Validation (Zod)
|
||
- **Schemas**: `src/lib/validations.ts` defines all Zod schemas
|
||
- `ProjectInputSchema`: Validates incoming project data
|
||
- `WebhookPayloadSchema`: Validates webhook requests with API key
|
||
- `ProjectQuerySchema`: Validates query parameters
|
||
|
||
### Styling (Tailwind CSS)
|
||
- **Neo-brutalism design**: Sharp corners, bold borders, hard shadows
|
||
- **Theme colors**: Primary gold (#FFD700), secondary orange, custom shadows (shadow-neo, shadow-brutal)
|
||
- **Dark mode**: Class-based with `dark:` prefix
|
||
- **Config**: `tailwind.config.ts` extends theme with custom colors, shadows, and animations
|
||
|
||
### UI Components
|
||
- **Radix UI primitives**: `@radix-ui/react-slot`, `@radix-ui/react-navigation-menu`, `@radix-ui/react-dropdown-menu`
|
||
- **Lucide React icons**: Used throughout the app
|
||
- **Custom components**: `src/components/` organized by domain (project/, locale/, search/)
|
||
|
||
## MCP Servers Usage (按需使用)
|
||
|
||
1. **context7**: 不确定 API 用法时查阅最新文档
|
||
2. **chrome-devtools-mcp**: 查看页面效果、调试 UI 修复 BUG
|
||
3. **dbhub mcp**: 查询数据库数据（PostgreSQL）
|
||
4. **shadcn mcp**: 确认 shadcn/ui 组件用法
|
||
5. **web-search-prime**: 默认联网搜索工具
|
||
6. **vision-mcp-server**: 图片/视频理解
|
||
|
||
## Git Commits
|
||
|
||
提交信息主要使用中文，使用描述性的提交格式。
|