docs: 生成层次化 AGENTS.md 文档系统

2026-02-01 14:57:43 +08:00
parent e1f250d397
commit 53e1faab89
5 changed files with 479 additions and 0 deletions
@@ -0,0 +1,49 @@
+# src/hooks/ - Server-Side Data Fetching
+
+**Purpose**: Server-side data fetching functions (NOT React hooks). Exported functions for use in Server Components and API routes.
+
+## Architecture
+
+- **Server Functions Only**: No React hooks, no client-side state
+- **Direct Prisma Queries**: ORM queries with optimization patterns
+- **ISR Support**: Used by Next.js App Router for incremental static revalidation
+
+## Key Functions
+
+### Project Data (`useProjects.ts`)
+
+- `getProjects()`: List projects with tags, pagination, filtering (search/tags/status)
+  - Flattens `ProjectTag` junction table to return tags directly
+  - Optimized for list queries with selective field loading
+- `getProjectBySlug(slug)`: Get single project by slug
+  - Used by ISR pages with 5-min revalidation
+  - Includes all tags and external links
+- `getAllTags()`: All tags with project counts
+- `getTagsWithProjectCounts()`: Tags sorted by popularity (count DESC)
+
+### Keyword Cloud (`useKeywordCloud.ts`)
+
+- `getAllQuarters()`: List all quarters with metadata
+- `getQuarterByQuarter(quarter)`: Single quarter with keyword count
+- `getKeywordsByQuarter(quarter)`: All keywords for a quarter
+- `getVisualStyleRules()`: Visual style configuration for word cloud
+
+## Query Optimization Patterns
+
+**N+1 Prevention**: Batch queries for related data (tags, links)
+**Selective Loading**: Only fetch required fields via Prisma `select`
+**Index Utilization**: Leverages database indexes (status+createdAt, slug, etc.)
+**Pagination**: Limit/offset to prevent large result sets
+
+## ISR Strategy
+
+- **Revalidation**: 5-minute revalidate on project detail pages
+- **Stale Data Acceptable**: Project listings tolerate slight staleness
+- **Cache Busting**: Use `revalidatePath()` when data changes via webhook
+
+## Best Practices
+
+- Always import via `@/hooks/use*` (not relative paths)
+- Return plain objects/arrays, never Prisma model instances
+- Handle errors at route level, not in these functions
+- Add new functions to existing files or create new `use*.ts` files