From 6303fd7ae62cb1618e6f7bfc91e67716ebdb6cac Mon Sep 17 00:00:00 2001 From: Caihaohan Date: Mon, 29 Dec 2025 19:58:18 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20CLAUDE.md=20?= =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 补充项目路由结构说明 - 添加数据库多级去重策略详细说明 - 新增数据获取、内容渲染、UI 组件等架构文档 - 补充 Next.js 配置说明 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 64 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 51 insertions(+), 13 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0942c2f..0affaf8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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运行。如果有的话请直接访问，如果没有的话再执行相关命令启动项目。