docs: 完善 CLAUDE.md 项目文档
- 补充项目路由结构说明 - 添加数据库多级去重策略详细说明 - 新增数据获取、内容渲染、UI 组件等架构文档 - 补充 Next.js 配置说明 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
@@ -42,7 +42,9 @@ This is a **Next.js 15 multilingual AI project navigation website** using the Ap
|
||||
src/app/
|
||||
├── [locale]/ # Locale-scoped routes
|
||||
│ ├── page.tsx # Home page
|
||||
│ ├── projects/ # Projects listing
|
||||
│ ├── 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
|
||||
@@ -53,30 +55,64 @@ src/app/
|
||||
- **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
|
||||
- **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)
|
||||
2. **Website URL exact match**
|
||||
3. **slug match** (fallback)
|
||||
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
|
||||
- `WebhookPayloadSchema`: Validates webhook requests with API key
|
||||
- `ProjectQuerySchema`: Validates query parameters
|
||||
- `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, bold borders, hard shadows
|
||||
- **Theme colors**: Primary gold (#FFD700), secondary orange, custom shadows (shadow-neo, shadow-brutal)
|
||||
- **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`
|
||||
- **Lucide React icons**: Used throughout the app
|
||||
- **Custom components**: `src/components/` organized by domain (project/, locale/, search/)
|
||||
- **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 (按需使用)
|
||||
|
||||
@@ -90,3 +126,5 @@ The webhook at `src/app/api/webhook/projects/route.ts` implements a **multi-leve
|
||||
## Git Commits
|
||||
|
||||
提交信息主要使用中文，使用描述性的提交格式。
|
||||
|
||||
如果你需要查看页面 请不要直接启动项目 而是应该先检查是否已经有启动好的项目在localhost:3000运行。如果有的话请直接访问，如果没有的话再执行相关命令启动项目。
|
||||
|
||||
Reference in New Issue
Block a user