mzaxd
6cb4545a17
- 更新 AGENTS.md 项目知识库文档（多目录） - 添加 docs/analyst.md 产品分析文档 - 添加 .omc/ 工具状态和会话记录 - 添加 .sisyphus/ 计划文档 - 添加 project-structure.txt 项目结构 - 删除 timeline 测试截图
69 lines
1.9 KiB
Markdown
69 lines
1.9 KiB
Markdown
# src/lib/ - Core Utilities
|
|
|
|
<!-- Parent: ../AGENTS.md -->
|
|
|
|
## Overview
|
|
|
|
Shared utilities and infrastructure layers used across the application.
|
|
|
|
## Key Files
|
|
|
|
### Validation Layer (`validations.ts`)
|
|
|
|
**Purpose**: Input validation and type safety using Zod schemas
|
|
|
|
- `ProjectInputSchema`: Project data validation (1-10 tags, 1-10 links)
|
|
- `WebhookPayloadSchema`: Webhook request validation with API key auth
|
|
- `KeywordInputSchema`: Keyword cloud data with visual config
|
|
- `ProjectQuerySchema`: Query parameter validation (search, tags, status, pagination)
|
|
- `ExternalLinkSchema`: URL validation with http/https protocol check
|
|
- `TaskStatusEnum`: Discovery task states (PENDING/IN_PROGRESS/COMPLETED/FAILED)
|
|
|
|
### Prisma Client (`prisma.ts`)
|
|
|
|
**Purpose**: Singleton database client pattern
|
|
|
|
```typescript
|
|
import { prisma } from "@/lib/prisma";
|
|
```
|
|
|
|
### Utilities
|
|
|
|
- `utils.ts`: `cn()` - Tailwind class merging with clsx/twMerge
|
|
- `slug.ts`: `generateSlug()` - URL-friendly slug generation (prefers English, max 100 chars)
|
|
|
|
### GitHub Integration
|
|
|
|
- `github/api.ts`: `getGitHubStats()` - Fetch repo stats (stars, forks, license) with 5min cache
|
|
- `github/badges.ts`: `parseGitHubUrl()`, `getGitHubStarsBadgeUrl()`, `getAllGitHubBadgeUrls()`
|
|
|
|
## Usage Patterns
|
|
|
|
**Validation**:
|
|
|
|
```typescript
|
|
import { ProjectInputSchema } from "@/lib/validations";
|
|
const validated = ProjectInputSchema.parse(inputData);
|
|
```
|
|
|
|
**Database**:
|
|
|
|
```typescript
|
|
import { prisma } from "@/lib/prisma";
|
|
const projects = await prisma.project.findMany();
|
|
```
|
|
|
|
**GitHub Badges**:
|
|
|
|
```typescript
|
|
import { getGitHubBadgesFromLinks } from "@/lib/github/badges";
|
|
const { stars } = getGitHubBadgesFromLinks(project.externalLinks);
|
|
```
|
|
|
|
## Key Design Decisions
|
|
|
|
- Singleton Prisma client prevents connection pool exhaustion in dev
|
|
- All enums use Zod for runtime type checking
|
|
- API key minimum length: 32 characters
|
|
- URL validation enforces http/https protocol only
|