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

任务: Agent Park - AI项目导航网站

输入: 来自 /specs/001-ai-project-navigator/ 的设计文档 前置条件: plan.md, spec.md, data-model.md, contracts/webhook.yaml, research.md, quickstart.md

测试: 本任务清单不包含测试任务。根据章程要求测试驱动开发, 但实际实现可按需决定是否编写测试。

组织结构: 任务按用户故事分组, 以便每个故事能够独立实施和测试。

格式: [ID] [P] [Story] 描述

• [P]: 可以并行运行(不同文件, 无依赖关系)
• [Story]: 此任务属于哪个用户故事(例如: US1、US2、US3、US4)
• 在描述中包含确切的文件路径

路径约定

• 单一项目: 仓库根目录下的 src/、tests/、prisma/

---

阶段 1: 设置(共享基础设施)

目的: 项目初始化和基本结构

• T001 创建 Next.js 14+ 项目并配置 TypeScript 严格模式
• T002 安装核心依赖包
• T003 [P] 配置 ESLint 和 Prettier
• T004 [P] 配置 Tailwind CSS
• T005 [P] 配置 shadcn/ui 组件库
• T006 [P] 配置 next-intl 国际化

---

阶段 2: 基础(阻塞前置条件)

目的: 在任何用户故事可以实施之前必须完成的核心基础设施

⚠️ 关键: 在此阶段完成之前, 无法开始任何用户故事工作

• T007 设置 PostgreSQL 数据库
• T008 创建 Prisma schema 定义
• T009 执行 Prisma 初始迁移
• T010 生成 Prisma Client
• T011 创建 Zod 验证 schemas
• T012 创建 Prisma 客户端单例
• T013 创建种子数据脚本
• T014 配置 Next.js 国际化路由结构
• T015 创建环境变量配置文件

检查点: 基础就绪 - 现在可以开始并行实施用户故事

---

阶段 3: 用户故事 1 - 浏览和搜索AI项目(优先级: P1)🎯 MVP

目标: 用户可以通过浏览标签云、搜索关键词、筛选标签来发现AI项目

独立测试: 访问首页可以看到热门标签云和精选项目;输入搜索关键词可看到相关项目;点击标签可以筛选项目

用户故事 1 的实施

• T016 [P] [US1] 创建首页布局组件 src/app/[locale]/layout.tsx
• T017 [P] [US1] 创建 Header 导航组件 src/components/layout/Header.tsx
• T018 [P] [US1] 创建 Footer 组件 src/components/layout/Footer.tsx
• T019 [P] [US1] 创建 Navigation 组件 src/components/layout/Navigation.tsx
• T020 [P] [US1] 创建 TagCloud 组件 src/components/project/TagCloud.tsx
• T021 [P] [US1] 创建 ProjectCard 组件 src/components/project/ProjectCard.tsx
• T022 [P] [US1] 创建 ProjectList 组件 src/components/project/ProjectList.tsx
• T023 [P] [US1] 创建 SearchBar 组件 src/components/search/SearchBar.tsx
• T024 [US1] 实现首页 src/app/[locale]/page.tsx(依赖于 T016-T023)
• T025 [US1] 实现项目列表页路由 src/app/[locale]/projects/page.tsx
• T026 [US1] 创建 useSearch hook src/hooks/useSearch.ts
• T027 [US1] 创建 useProjects hook src/hooks/useProjects.ts
• T028 [US1] 添加国际化翻译文件 src/messages/zh.json 和 src/messages/en.json
• T029 [US1] 配置 ISR 缓存策略优化页面性能

检查点: 此时, 用户应该能够访问首页、浏览项目、使用搜索和标签筛选功能

---

阶段 4: 用户故事 2 - 查看项目详细信息(优先级: P1)

目标: 用户点击项目卡片后可以查看项目完整信息和外部链接

独立测试: 点击任意项目卡片进入详情页, 验证显示项目描述、标签、外部链接, 点击链接在新标签页打开

用户故事 2 的实施

• T030 [P] [US2] 创建 ProjectDetail 组件 src/components/project/ProjectDetail.tsx
• T031 [P] [US2] 创建 ExternalLinkCard 组件 src/components/project/ExternalLinkCard.tsx
• T032 [US2] 实现项目详情页路由 src/app/[locale]/projects/[id]/page.tsx(依赖于 T030、T031)
• T033 [US2] 添加项目详情页的国际化翻译
• T034 [US2] 实现外部链接的 target="_blank" 安全属性

检查点: 此时, 用户故事 1 和用户故事 2 都应该完全功能化且可独立测试

---

阶段 5: 用户故事 3 - 响应式设计体验(优先级: P2)

目标: 网站在桌面、平板、手机等不同设备上都能正常显示和操作

独立测试: 在不同屏幕尺寸下访问网站, 验证布局自动调整且所有功能可用

用户故事 3 的实施

• T035 [P] [US3] 更新 Header 组件支持响应式布局
• T036 [P] [US3] 更新 Navigation 组件支持移动端菜单
• T037 [P] [US3] 更新 ProjectCard 组件支持不同屏幕尺寸
• T038 [P] [US3] 更新 ProjectList 组件支持响应式网格布局
• T039 [P] [US3] 更新 SearchBar 组件支持移动端输入
• T040 [US3] 更新 ProjectDetail 组件支持响应式布局
• T041 [US3] 配置 Tailwind 响应式断点
• T042 [US3] 测试并优化移动端触摸交互

检查点: 此时, 所有用户故事(US1、US2、US3)都应该独立功能化且支持响应式

---

阶段 6: 用户故事 4 - 数据更新和管理(优先级: P3)

目标: 提供 webhook API 接口, 接收 n8n 工作流程推送的 AI 项目数据更新

独立测试: 使用 curl 或 Postman 模拟 n8n 推送请求, 验证新数据能够正确更新到数据库

用户故事 4 的实施

• T043 [P] [US4] 创建 WebhookAuthSchema 验证
• T044 [P] [US4] 创建 WebhookPayloadSchema 验证
• T045 [P] [US4] 创建 ProjectInputSchema 验证
• T046 [US4] 实现 webhook API 端点 src/app/api/webhook/projects/route.ts(依赖于 T043-T045)
• T047 [US4] 实现 API Key 身份验证中间件
• T048 [US4] 实现部分成功模式的批量数据处理逻辑
• T049 [US4] 添加 webhook 请求日志记录
• T050 [US4] 添加 webhook 错误处理和响应格式
• T051 [US4] 配置 webhook API 的环境变量
• T052 [US4] 编写 webhook API 使用文档

检查点: 此时, 所有用户故事现在应该完全功能化

---

阶段 7: 完善与横切关注点

目的: 影响多个用户故事的改进

• T053 [P] 全局样式优化实现 Anthropic Claude 风格
• T054 [P] 优化 Core Web Vitals 性能指标
• T055 [P] 添加 loading 和 skeleton 状态提升用户体验
• T056 [P] 实现 404 和错误页面
• T057 [P] 添加 SEO 元数据配置
• T058 配置 next.config.js 优化
• T059 创建 README.md 项目文档
• T060 运行 quickstart.md 验证完整流程

---

依赖关系与执行顺序

阶段依赖关系

• 设置(阶段 1): 无依赖关系 - 可立即开始
• 基础(阶段 2): 依赖于设置完成 - 阻塞所有用户故事
• 用户故事(阶段 3-6): 都依赖于基础阶段完成
  • US1 和 US2 都是 P1 优先级, 可以并行开发
  • US3 (P2) 可以在 US1/US2 基础上进行响应式优化
  • US4 (P3) 是独立的后台功能, 可并行开发
• 完善(阶段 7): 依赖于所有期望的用户故事完成

用户故事依赖关系

• 用户故事 1 (P1): 可在基础(阶段 2)后开始 - 无其他故事依赖
• 用户故事 2 (P1): 可在基础(阶段 2)后开始 - 可与 US1 并行开发
• 用户故事 3 (P2): 依赖于 US1 和 US2 完成 - 在现有组件基础上添加响应式支持
• 用户故事 4 (P3): 可在基础(阶段 2)后开始 - 独立的 API 功能

每个用户故事内部

• US1: 布局和基础组件 [P] 并行 → 页面路由集成 → hooks 和国际化
• US2: 组件 [P] 并行 → 页面路由实现
• US3: 组件响应式更新 [P] 并行 → 全局配置
• US4: Schema 定义 [P] 并行 → API 端点实现 → 日志和错误处理

并行机会

• 所有标记为 [P] 的设置任务(T003-T006)可以并行运行
• US1 的所有布局和基础组件(T016-T023)可以并行开发
• US2 的组件(T030-T031)可以并行开发
• US3 的响应式更新(T035-T039)可以并行进行
• US4 的所有 Schema 定义(T043-T045)可以并行开发
• US1 和 US2 可以由不同团队成员并行处理
• US4 可以与 US1/US2/US3 并行开发(独立的后端功能)

---

并行示例: 用户故事 1 (US1)

# 一起启动用户故事 1 的所有布局和基础组件(可并行):
T016: "创建首页布局组件 src/app/[locale]/layout.tsx"
T017: "创建 Header 导航组件 src/components/layout/Header.tsx"
T018: "创建 Footer 组件 src/components/layout/Footer.tsx"
T019: "创建 Navigation 组件 src/components/layout/Navigation.tsx"
T020: "创建 TagCloud 组件 src/components/project/TagCloud.tsx"
T021: "创建 ProjectCard 组件 src/components/project/ProjectCard.tsx"
T022: "创建 ProjectList 组件 src/components/project/ProjectList.tsx"
T023: "创建 SearchBar 组件 src/components/search/SearchBar.tsx"

---

实施策略

仅 MVP(用户故事 1 + 2)

1. 完成阶段 1: 设置(T001-T006)
2. 完成阶段 2: 基础(T007-T015)
3. 完成阶段 3: 用户故事 1(T016-T029)
4. 完成阶段 4: 用户故事 2(T030-T034)
5. 停止并验证: 独立测试核心浏览、搜索和详情功能
6. 如准备好则部署/演示

增量交付

1. 完成设置 + 基础(T001-T015) → 基础就绪
2. 添加用户故事 1(T016-T029) → 独立测试 → 部署/演示(MVP!)
3. 添加用户故事 2(T030-T034) → 独立测试 → 部署/演示
4. 添加用户故事 3(T035-T042) → 独立测试 → 部署/演示
5. 添加用户故事 4(T043-T052) → 独立测试 → 部署/演示
6. 添加完善(T053-T060) → 最终部署

并行团队策略

有多个开发人员时:

1. 团队一起完成设置 + 基础(T001-T015)
2. 基础完成后:
   • 开发人员 A: 用户故事 1(T016-T029)
   • 开发人员 B: 用户故事 2(T030-T034)
   • 开发人员 C: 用户故事 4(T043-T052)
3. US1 和 US2 完成后, 开发人员 A/B 转向用户故事 3(T035-T042)
4. 所有故事完成后, 团队一起进行完善(T053-T060)

---

注意事项

• [P] 任务 = 不同文件, 无依赖关系
• [Story] 标签将任务映射到特定用户故事以实现可追溯性
• 每个用户故事应该独立可完成和可测试
• 在每个任务或逻辑组后提交
• 在任何检查点停止以独立验证故事
• 避免: 模糊任务、相同文件冲突、破坏独立性的跨故事依赖

---

摘要统计

• 总任务数: 60 个任务
• 阶段数: 7 个阶段
• 用户故事数: 4 个用户故事
  • US1 (P1): 14 个任务
  • US2 (P1): 5 个任务
  • US3 (P2): 8 个任务
  • US4 (P3): 10 个任务
• 并行任务数: 约 35 个任务标记为 [P] 可并行
• MVP 范围: 阶段 1-4 (T001-T034), 共 34 个任务