mzaxdandClaude
6303fd7ae6
- 补充项目路由结构说明 - 添加数据库多级去重策略详细说明 - 新增数据获取、内容渲染、UI 组件等架构文档 - 补充 Next.js 配置说明 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
131 lines
5.8 KiB
Markdown
131 lines
5.8 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 and details
|
||
│ │ ├── page.tsx # Projects list
|
||
│ │ └── [id]/ # Individual project details (slug-based)
|
||
│ └── 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`, `content`/`contentEn` pairs
|
||
- **Indexes**: `idx_project_status_createdAt`, `idx_project_slug`, `idx_tag_slug`, `idx_link_projectId`, `idx_link_type`
|
||
|
||
### 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) - via `ExternalLink` table
|
||
2. **Website URL exact match** - via `ExternalLink` table
|
||
3. **slug match** (fallback) - via `Project.slug` field
|
||
|
||
When updating an existing project, the webhook:
|
||
- Updates all project fields (name, description, content, status, source)
|
||
- Replaces all tags (deletes old connections, creates new ones)
|
||
- Replaces all links (deletes old links, creates new ones)
|
||
|
||
### Data Fetching (Server-Side)
|
||
- **Location**: `src/hooks/useProjects.ts` (server functions, not React hooks)
|
||
- **Functions**: `getProjects()`, `getProjectBySlug()`, `getAllTags()`, `getTagsWithProjectCounts()`
|
||
- **Usage**: Directly called in Server Components and route handlers
|
||
- **ISR**: Project detail pages use `export const revalidate = 300` (5 minutes)
|
||
|
||
### Validation (Zod)
|
||
- **Schemas**: `src/lib/validations.ts` defines all Zod schemas
|
||
- `ProjectInputSchema`: Validates incoming project data (1-10 tags, 1-10 links required)
|
||
- `WebhookPayloadSchema`: Validates webhook requests with API key (1-100 projects per request)
|
||
- `ProjectQuerySchema`: Validates query parameters (search, tags, status, page, limit)
|
||
|
||
### Styling (Tailwind CSS)
|
||
- **Neo-brutalism design**: Sharp corners (0px radius), bold borders (4px shadows), hard edges
|
||
- **Theme colors**:
|
||
- Primary: Gold (#FFD700)
|
||
- Secondary: Orange (#ff6f00)
|
||
- Background light: #F5F2EB, dark: #121212
|
||
- Surface light: #FFFFFF, dark: #1E1E1E
|
||
- **Typography**: Space Mono (headings), Inter (body)
|
||
- **Dark mode**: Class-based with `dark:` prefix
|
||
- **Config**: `tailwind.config.ts` extends theme with custom colors, shadows, and animations
|
||
|
||
### Content Rendering
|
||
- **Markdown**: Project content fields support Markdown via `react-markdown`
|
||
- **Plugins**: `rehype-raw`, `rehype-sanitize`, `rehype-shiki`, `remark-gfm`
|
||
- **Usage**: `ProjectDetail` component renders `content`/`contentEn` as Markdown
|
||
|
||
### UI Components
|
||
- **Radix UI primitives**: `@radix-ui/react-slot`, `@radix-ui/react-navigation-menu`, `@radix-ui/react-dropdown-menu`, `@radix-ui/react-separator`
|
||
- **Lucide React icons**: Used throughout the app (package imports optimized via `experimental.optimizePackageImports`)
|
||
- **Custom components**: `src/components/` organized by domain
|
||
- `layout/`: Header, Footer
|
||
- `locale/`: LocaleSwitcher
|
||
- `project/`: ProjectCard, ProjectList, ProjectDetail, ProjectSidebar, RelatedProjects, TagCloud, ExternalLinkCard
|
||
- `search/`: SearchBar
|
||
- `ui/`: Base UI components (buttons, cards, etc.)
|
||
|
||
### Next.js Configuration
|
||
- **next.config.js**:
|
||
- `next-intl` plugin wrapper for i18n
|
||
- Image domains: localhost, *.anthropic.com
|
||
- Lucide-react package import optimization
|
||
- **tsconfig.json**: ES2022 target, strict mode enabled
|
||
|
||
## 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
|
||
|
||
提交信息主要使用中文，使用描述性的提交格式。
|
||
|
||
如果你需要查看页面 请不要直接启动项目 而是应该先检查是否已经有启动好的项目在localhost:3000运行。如果有的话请直接访问，如果没有的话再执行相关命令启动项目。
|