agent-park/specs/001-ai-project-navigator/plan.md

实施计划: Agent Park - AI项目导航网站

分支: 001-ai-project-navigator | 日期: 2025-12-25 | 规范: spec.md 输入: 来自 /specs/001-ai-project-navigator/spec.md 的功能规范

摘要

构建一个名为 Agent Park 的全网AI项目导航网站，采用 Anthropic Claude 风格设计。网站支持中英双语，使用 Next.js 14+ App Router、shadcn/ui 组件库、Prisma ORM + PostgreSQL 数据库、Tailwind CSS。用户可以浏览、搜索AI项目，查看项目详情和外部链接。前期使用20-30个假数据构建，后期通过 webhook 接口接收 n8n 工作流程推送的更新数据。

技术背景

语言/版本: TypeScript 5.0+ (严格模式) 主要依赖:

• Next.js 14+ (App Router)
• shadcn/ui (组件库)
• Prisma (ORM)
• PostgreSQL (数据库)
• Tailwind CSS (样式)
• next-intl (国际化)
• Zod (数据验证)

存储: PostgreSQL (通过 Prisma ORM) 测试: Vitest + React Testing Library + Playwright 目标平台: Web (响应式设计 - 桌面/平板/手机) 项目类型: 全栈 Web 应用 性能目标:

• 首次内容绘制(FCP) < 1.8s
• 最大内容绘制(LCP) < 2.5s
• 首次字节时间(TTFB) < 800ms
• 初始 JavaScript < 200KB gzipped

约束条件:

• TypeScript 严格模式强制启用
• 单元测试覆盖率 80%+
• 所有代码必须通过 ESLint 检查
• 禁止使用 @ts-ignore

规模/范围:

• 前期: 20-30个项目数据
• 页面: 首页、项目列表、项目详情页
• API: 1个 webhook 接口 (POST /api/webhook/projects)

章程检查

*门控: 必须在阶段 0 研究前通过. 阶段 1 设计后重新检查. *

阶段 0 前检查

原则	状态	说明
I. TypeScript 严格模式与类型安全	✅ 通过	项目使用 TypeScript 5.0+ 严格模式，所有 API 使用 Zod 验证
II. 组件优先架构	✅ 通过	使用 Next.js App Router，优先 Server Components
III. 测试驱动开发(不可协商)	✅ 通过	规划使用 Vitest + React Testing Library + Playwright，目标 80%+ 覆盖率
IV. 性能优先	✅ 通过	定义了明确的 Core Web Vitals 目标，使用 ISR 和 SSG 优化
V. 用户体验一致性	✅ 通过	使用 shadcn/ui 统一设计系统，支持响应式和深色模式
VI. 代码质量与可维护性	✅ 通过	使用 ESLint + Prettier，遵循 TypeScript 最佳实践

阶段 1 后重新检查

原则	状态	说明
所有阶段 0 门控项	✅ 保持	设计确认符合所有章程原则
数据模型类型安全	✅ 通过	Prisma 生成类型，配合 Zod 运行时验证
API 合同完整性	✅ 通过	webhook 接口使用 Zod schema 验证输入

结论: 项目设计完全符合章程要求，无违规项。

项目结构

文档(此功能)

specs/001-ai-project-navigator/
├── plan.md              # 此文件 (/speckit.plan 命令输出)
├── research.md          # 阶段 0 输出 - 技术选型研究
├── data-model.md        # 阶段 1 输出 - 数据模型设计
├── quickstart.md        # 阶段 1 输出 - 快速开始指南
├── contracts/           # 阶段 1 输出 - API 合同
│   └── webhook.yaml     # OpenAPI 3.0 规范
└── tasks.md             # 阶段 2 输出 (/speckit.tasks 命令)

源代码(仓库根目录)

agent-park-v2/
├── prisma/
│   ├── schema.prisma           # Prisma 数据模型定义
│   └── seed.ts                 # 假数据种子脚本
├── public/
│   └── images/                 # 静态图片资源
├── src/
│   ├── app/                    # Next.js App Router 目录
│   │   ├── [locale]/           # next-intl 国际化路由
│   │   │   ├── layout.tsx      # 根布局
│   │   │   ├── page.tsx        # 首页
│   │   │   ├── projects/       # 项目列表页
│   │   │   │   ├── page.tsx
│   │   │   │   └── [id]/       # 项目详情页
│   │   │   │       └── page.tsx
│   │   │   └── api/            # API 路由
│   │   │       └── webhook/
│   │   │           └── projects/
│   │   │               └── route.ts    # Webhook 端点
│   │   ├── globals.css         # Tailwind 全局样式
│   │   └── layout.tsx          # 根布局 (国际化)
│   ├── components/             # React 组件
│   │   ├── ui/                 # shadcn/ui 组件 (自动生成)
│   │   ├── layout/             # 布局组件
│   │   │   ├── Header.tsx
│   │   │   ├── Footer.tsx
│   │   │   └── Navigation.tsx
│   │   ├── project/            # 项目相关组件
│   │   │   ├── ProjectCard.tsx
│   │   │   ├── ProjectList.tsx
│   │   │   ├── ProjectDetail.tsx
│   │   │   └── TagCloud.tsx
│   │   └── search/             # 搜索组件
│   │       ├── SearchBar.tsx
│   │       └── SearchResults.tsx
│   ├── lib/                    # 工具库
│   │   ├── prisma.ts           # Prisma 客户端单例
│   │   ├── utils.ts            # 通用工具函数
│   │   └── validations.ts      # Zod 验证 schemas
│   ├── hooks/                  # 自定义 Hooks
│   │   ├── useSearch.ts
│   │   └── useProjects.ts
│   ├── types/                  # TypeScript 类型定义
│   │   └── index.ts
│   ├── messages/               # next-intl 翻译文件
│   │   ├── en.json
│   │   └── zh.json
│   └── styles/                 # 额外样式文件
├── tests/                      # 测试文件
│   ├── unit/                   # 单元测试
│   ├── integration/            # 集成测试
│   └── e2e/                    # E2E 测试 (Playwright)
├── next.config.js              # Next.js 配置
├── tailwind.config.js          # Tailwind CSS 配置
├── tsconfig.json               # TypeScript 配置
├── components.json             # shadcn/ui 配置
├── .env.example                # 环境变量示例
├── package.json
└── README.md

结构决策: 采用标准的 Next.js App Router 单体项目结构。所有源代码在 src/ 目录下，使用 app/ 目录进行路由。Prisma schema 在根目录 prisma/ 文件夹。组件按功能分目录组织，shadcn/ui 组件放在 components/ui/ 自动管理。

复杂度跟踪

仅在章程检查有必须证明的违规时填写

无违规项。项目设计完全符合章程要求。

违规	为什么需要	拒绝更简单替代方案的原因
-	-	-