黑客松活动系统需求文档

开发进度 Todo List

第一阶段：MVP 核心功能

数据库扩展

• ✅ Project 表扩展 - 添加黑客松特有字段（githubUrl, slidesUrl, inspiration, challenges, learnings, nextSteps）
• ✅ Event 表扩展 - 黑客松配置存储（hackathonConfig JSON字段）
• ✅ 团队成员管理 - 通过ProjectMember关联User表

后端 API 开发（基于 Hono.js）

• ✅ 扩展事件项目提交API以支持黑客松字段和团队成员管理
• ✅ 创建黑客松配置管理API（GET/PUT /events/:eventId/hackathon-config）
• ✅ 实现观众投票API（POST /events/:eventId/submissions/:submissionId/vote）
• ✅ 黑客松投票结果API（GET /events/:eventId/voting-results）

前端黑客松界面

• ✅ 创建HackathonEventPage主页面组件
• ✅ 创建HackathonProjectSubmissionForm项目提交表单组件
• ✅ 创建TeamMemberSelector团队成员选择器组件
• ✅ 创建HackathonProjectGallery项目展示画廊组件
• ✅ 创建VotingPanel投票面板组件
• ✅ 创建AwardShowcase获奖展示组件
• ✅ 集成黑客松页面到EventDetailsClient中

下一步计划

• ✅ 运行完整的类型检查和测试
• 添加国际化翻译文本
• 完善移动端适配

🎉 第一阶段完成总结

恭喜！黑客松系统的第一阶段MVP核心功能已全部完成！

✨ 已实现的核心功能

1. 完整的数据库架构

   • Project表扩展支持黑客松特有字段
   • Event表支持黑客松配置存储
   • ProjectMember模型实现团队协作

2. 强大的后端API系统

   • 项目提交API支持团队成员管理
   • 黑客松配置管理API
   • 双重投票系统（观众+评委）
   • 实时投票结果API

3. 完整的前端界面

   • 专业的黑客松活动页面
   • 直观的项目提交表单
   • 智能的团队成员选择器
   • 精美的项目展示画廊
   • 实时的投票面板
   • 漂亮的获奖展示

4. 系统特色功能

   • 🎯 学习导向：支持记录灵感来源、技术挑战、学习收获等
   • 👥 团队协作：灵活的团队规模配置和成员管理
   • 🗳️ 双重投票：观众投票+评委评分，权重可配置
   • 📊 实时结果：动态排行榜和获奖展示
   • 🎨 现代界面：响应式设计，支持多种设备

🔧 技术实现亮点

• 类型安全：完整的TypeScript类型定义
• API设计：基于Hono.js的RESTful API
• 组件化：模块化的React组件架构
• 权限控制：基于配置的细粒度权限管理
• 扩展性：灵活的JSON配置支持未来扩展

1. 背景与愿景

1.1 社区背景

周周黑客松是一个充满温暖的创作者社区，核心理念是：

• 持续学习：通过实践快速掌握 AI 工具和新技术
• 快速创造：在有限时间内产出可运行的 MVP
• 温暖分享：在支持性的环境中展示作品，获得建设性反馈
• 低门槛参与：新手友好，重过程而非结果

1.2 活动定位

统一使用 HACKATHON 活动类型，通过时长和配置来区分不同规模的活动：

• 迷你黑客松：8-12小时，快速原型开发
• 两天黑客松：48小时，完整MVP构建

1.3 与传统黑客松的区别

传统竞赛型黑客松：

• 强调竞争和排名
• 评委打分决定优胜者
• 奖金驱动参与
• 结果导向

周周黑客松（学习型）：

• 强调学习和成长
• 社区互评和反馈
• 内在动机驱动
• 过程导向，鼓励迭代

1.4 系统设计原则

• 复用现有系统：在现有Event系统基础上扩展，复用活动反馈、通知、统计等所有功能，利用已有的 Project User Profile 等模块（已有的 event 已经关联了）
• 最小改动：优先使用JSON配置，避免大规模schema变更
• 功能扩展：黑客松仅增加项目提交、投票、颁奖等专有功能，其他功能均复用

2. 黑客松活动闭环设计

2.1 完整活动流程

活动生命周期：报名 → 提交 → 投票 → 颁奖 → 展示

阶段1：活动报名

• 用户通过活动页面报名参与黑客松
• 活动详情展示：时间、主题、奖项设置、评审机制 （复用 events 界面，但是有新增的 黑客松信息卡片）
• 支持团队报名（团队成员必须是注册用户）

阶段2：项目提交

• 已报名用户可提交现有项目或创建新项目参与
• 项目信息：标题、描述、演示链接（可选）、GitHub（可选）、在线幻灯片（slide_url 可选）
• 团队信息：邀请注册用户作为团队成员
• 黑客松特色内容：灵感来源、技术挑战、学习收获、下一步计划

阶段3：双重投票

• 观众投票：所有参与者和公众可投票，产生"最受欢迎奖"类奖项
• 评委投票：指定评委进行专业评审，产生排名奖项（冠亚季军等）
• 投票时间可配置

阶段4：现场颁奖

• 根据投票结果自动或手动颁奖
• 支持现场上传获奖图片（合影、颁奖瞬间等）
• 自动发放获奖徽章（替代电子证书）

阶段5：成果展示

• 活动页面展示所有参与项目
• 突出显示获奖项目和奖项信息
• 展示获奖徽章
• 项目按获奖情况、人气等多维度排序展示

2.2 典型场景举例

迷你黑客松（12小时）

周六 09:00 - 活动开始，项目提交开放
周六 12:00 - 中期进展分享（可选）
周六 18:00 - 项目提交截止
周六 18:30 - 项目展示环节
周六 19:30 - 投票开始（观众+评委）
周六 20:30 - 投票结束，现场颁奖

两天黑客松（48小时）

周五 19:00 - 活动启动，项目提交开放
周六 20:00 - Day 1 进展分享
周日 17:00 - 项目提交截止
周日 17:30 - 最终展示环节
周日 19:00 - 双重投票开始
周日 20:00 - 投票结束，颁奖典礼

3. 黑客松功能设计（在现有Event系统基础上扩展）

重要说明：黑客松活动是在现有活动系统上的扩展，不是独立系统。所有Event基础功能（活动创建、报名、反馈、通知等）均保留和复用。

3.1 数据模型扩展

3.1.1 复用现有EventProjectSubmission系统 ✅

经调研发现，系统已经有完善的项目提交系统，可直接复用：

现有优势：

• ✅ 完整的 API 实现（提交、更新、审核、删除）
• ✅ 评委投票系统（judgeScore, audienceScore, finalScore）
• ✅ 项目快照功能（projectSnapshot）
• ✅ 与 ProjectAward 系统集成
• ✅ Event 表已有 requireProjectSubmission 和 projectSubmissionDeadline 字段

现有 EventProjectSubmission 结构：

model EventProjectSubmission {
  id              String              @id @default(cuid())
  eventId         String
  projectId       String
  userId          String              // 提交者
  submissionType  SubmissionType      // 提交类型: HACKATHON_PROJECT
  
  // 提交信息
  title           String              // 提交标题
  description     String              // 本次提交的描述
  demoUrl         String?             // 演示链接
  sourceCode      String?             // 源码链接 (对应 githubUrl)
  presentationUrl String?             // 演示文档链接 (对应 slidesUrl)
  
  // 评分信息 (已支持双重投票)
  judgeScore      Float?              // 评委评分
  audienceScore   Float?              // 观众评分
  finalScore      Float?              // 最终得分
  
  // 项目快照
  projectSnapshot Json                // 项目信息快照
  
  // Relations
  awards          ProjectAward[]      // 获得的奖项 ✅
}

3.1.2 Project模型扩展

需要增加黑客松特有字段（主要用于项目展示）：

model Project {
  // ... 现有字段（title, description, url, projectTags等）
  
  // 黑客松相关字段（全部可选，降低参与门槛）
  githubUrl     String?   // GitHub仓库链接
  slidesUrl     String?   // 在线PPT链接（腾讯文档、飞书等）
  inspiration   String?   // 灵感来源和项目背景
  challenges    String?   // 开发过程中遇到的挑战
  learnings     String?   // 学到的新技能和经验
  nextSteps     String?   // 未来发展计划
}

3.1.3 团队成员管理

团队成员通过关联User表实现，无需JSON字段：

// 通过现有EventProjectSubmission中的projectId关联
// Project表中已有collaborators字段可用于团队成员关联
// 或通过ProjectMember中间表实现多对多关系
model ProjectMember {
  id        String @id @default(cuid())
  projectId String
  userId    String
  role      String? // 'LEADER' | 'MEMBER'
  project   Project @relation(fields: [projectId], references: [id])
  user      User    @relation(fields: [userId], references: [id])
}

3.1.4 黑客松配置存储

在 Event 表新增 JSON 配置字段：

model Event {
  // ... 现有字段
  hackathonConfig Json? // 黑客松专用配置
}

interface HackathonConfig {
  // 活动设置
  settings: {
    maxTeamSize: number      // 最大团队人数，默认5
    allowSolo: boolean       // 允许个人参与，默认true
    requireProject: boolean  // 是否必须提交项目，默认false
  }
  
  // 双重投票设置（可配置投票权限）
  voting: {
    allowPublicVoting: boolean       // 允许观众投票
    enableJudgeVoting: boolean       // 启用评委投票
    // showLiveResults: boolean         // 实时显示投票结果（不需要）
    judgeWeight: number              // 评委权重 (0-1)
    publicWeight: number             // 观众权重 (0-1)
    // 投票权限控制
    publicVotingScope: 'ALL' | 'REGISTERED' | 'PARTICIPANTS' // 观众投票范围
  }
  
  // 奖项设置
  awards: Array<{
    id: string
    name: string              // 最佳创意奖、最佳技术奖、人气奖等
    description: string
    awardType: 'JUDGE' | 'PUBLIC'  // 评委奖项或观众奖项
    maxWinners: number        // 获奖人数
  }>
  
  // 学习资源
  resources?: {
    tutorials: Array<{ title: string; url: string; description?: string }>
    tools: Array<{ name: string; url: string; description?: string }>
    examples: Array<{ title: string; url: string; description?: string }>
  }
}

3.2 黑客松专有功能设计

基于现有Event系统的投票与颁奖功能扩展

3.2.1 双重投票机制 ✅

已实现的功能：

• ✅ 评委投票：通过 EventProjectSubmission.judgeScore 实现
• ✅ 观众投票：通过 EventProjectSubmission.audienceScore 实现
• ✅ 综合评分：通过 EventProjectSubmission.finalScore 实现

需要扩展的功能：

• 🔄 观众投票可以复用现有 ProjectLike 系统，自动同步到 audienceScore
• 🔄 权限控制：根据配置决定谁可以参与观众投票

3.2.2 颁奖流程 ✅

• ✅ 复用现有ProjectAward系统：记录获奖信息
• 🔄 徽章系统集成：获奖自动触发徽章发放
• 🔄 徽章系统集成：获奖自动触发徽章发放
• 🔄 徽章系统集成：获奖自动触发徽章发放

3.3 API设计

3.3.1 复用现有API ✅

已存在的 API（无需重新开发）：

// 项目提交相关API（已实现）
POST /api/events/:eventId/submit-project     // 提交项目到活动
GET  /api/events/:eventId/submissions         // 获取活动的项目提交列表  
PUT  /api/submissions/:submissionId           // 更新项目提交
PUT  /api/submissions/:submissionId/review    // 审核项目提交（评委评分）
DELETE /api/submissions/:submissionId         // 删除项目提交

3.3.2 需要新增的API

// 黑客松配置管理
PUT  /api/events/:eventId/hackathon-config    // 设置黑客松配置

// 投票权限控制
POST /api/events/:eventId/judges              // 设置评委
GET  /api/events/:eventId/voting-results      // 获取投票结果（权重计算后）

// 观众投票（扩展现有ProjectLike）
POST /api/projects/:projectId/vote            // 观众投票（复用现有API）

// 徽章系统集成
POST /api/events/:eventId/award-badges        // 为获奖者发放徽章

4. 前端组件设计（基于现有Event组件扩展）

4.1 黑客松活动页面组件

src/modules/dashboard/events/components/hackathon/
├── HackathonEventPage.tsx      // 黑客松活动主页面
├── ProjectSubmissionForm.tsx   // 项目提交表单（复用现有）
├── TeamMemberSelector.tsx      // 团队成员选择器（新增）
├── HackathonProjectGallery.tsx // 项目展示画廊
├── VotingPanel.tsx            // 投票面板
└── AwardShowcase.tsx          // 获奖展示组件

4.2 状态管理

• 活动状态：报名期 → 提交期 → 投票期 → 颁奖期 → 展示期
• 项目状态：未提交 → 已提交 → 投票中 → 已获奖
• 权限管理：参与者、评委、组织者的不同权限

4.3 黑客松与传统活动的组件复用 ✅

• ✅ 活动基础功能：复用现有EventDetailsClient组件
• ✅ 活动报名：复用现有报名系统
• ✅ 活动反馈：复用现有反馈系统（EventFeedback）
• ✅ 活动统计：复用现有的数据分析功能

4.4 黑客松专有组件

• 🆕 HackathonProjectSubmissionForm：扩展现有项目提交表单，增加黑客松特有字段
• 🆕 TeamMemberSelector：团队成员选择器（复用EventAdminManager的用户搜索功能）
• 🆕 VotingPanel：投票面板（基于现有ProjectLike扩展）
• 🆕 HackathonProjectGallery：项目展示画廊（基于现有submissions展示）

5. 额外功能建议与优化点

5.1 建议实现的额外功能

5.1.1 实时进展更新

• 项目进度分享：允许团队在开发过程中分享进展截图、遇到的问题
• 社区互助：其他参与者可以提供建议和帮助
• 导师制度：经验丰富的开发者可以担任导师，提供指导

5.1.2 增强的项目展示

• 项目视频演示：支持上传项目演示视频（最佳实践）
• 技术栈可视化：自动解析项目使用的技术栈并可视化展示
• 项目影响力追踪：跟踪项目后续发展（GitHub stars、用户增长等）

5.1.3 社区建设功能

• 参与者名片：展示参与者的技能标签、项目经验
• 组队匹配系统：基于技能互补的智能组队推荐
• 黑客松成就系统：连续参与、多次获奖等成就徽章

5.1.4 活动运营工具

• 活动模板系统：快速复制成功的黑客松配置
• 数据分析面板：参与率、完成率、满意度等数据分析
• 自动化通知：关键时间节点的自动提醒（报名开始、提交截止等）

5.2 需要优化的点

5.2.1 用户体验优化

• 移动端适配：确保在手机上也能流畅参与和投票
• 离线支持：在网络不稳定时也能继续开发和记录进展
• 多语言支持：支持中英文切换，方便国际参与者

5.2.2 技术优化

• 数据安全优化：实现投票结果、项目提交的安全存储
• 项目反馈系统优化
• CDN加速：为项目演示、幻灯片等静态资源提供CDN加速

5.2.3 社区生态优化

• 项目孵化：优秀项目可以继续在社区得到支持和发展
• 合作伙伴集成：与AI工具提供商、云服务商的深度集成
• 开源贡献：鼓励将黑客松项目开源，促进社区知识共享

5.3 潜在技术风险与应对

5.3.1 并发投票处理

• 风险：投票高峰期可能出现系统压力
• 应对：使用Redis缓存投票数据，批量写入数据库

5.3.2 数据存储管理

• 风险：大量项目数据可能占用存储空间
• 应对：实现数据自动压缩、定期清理过期数据

5.3.3 团队权限管理

• 风险：团队成员权限分配可能引发争议
• 应对：明确项目提交者为主要负责人，其他成员为协作者

6. 两阶段实施计划（基于 Hono.js + Prisma 技术栈）

6.1 第一阶段：MVP 核心功能（保证基本可用）

实施目标：完整的黑客松活动闭环，基础功能可用

6.1.1 数据库扩展

1. Project 表扩展 - 添加黑客松特有字段

   ALTER TABLE "Project" ADD COLUMN "githubUrl" TEXT;
   ALTER TABLE "Project" ADD COLUMN "slidesUrl" TEXT;
   ALTER TABLE "Project" ADD COLUMN "inspiration" TEXT;
   ALTER TABLE "Project" ADD COLUMN "challenges" TEXT;
   ALTER TABLE "Project" ADD COLUMN "learnings" TEXT;
   ALTER TABLE "Project" ADD COLUMN "nextSteps" TEXT;

2. Event 表扩展 - 黑客松配置存储

   ALTER TABLE "Event" ADD COLUMN "hackathonConfig" JSONB;

3. 团队成员管理 - 通过关联User表

   -- 如需要可创建ProjectMember中间表，或复用现有Project.collaborators字段
   -- 不需要在EventProjectSubmission中添加JSON字段

6.1.2 后端 API 开发（基于 Hono.js）

1. 扩展 src/server/routes/event-projects.ts

   • 在项目提交 API 中添加团队成员字段支持
   • 扩展项目提交表单验证 schema

2. 新建 src/server/routes/hackathon.ts

   • PUT /events/:eventId/hackathon-config - 设置黑客松配置
   • GET /events/:eventId/hackathon-config - 获取黑客松配置
   • POST /events/:eventId/submissions/:submissionId/vote - 观众投票

3. 扩展投票权限控制

   • 基于 hackathonConfig.voting.publicVotingScope 实现权限检查
   • 直接操作 EventProjectSubmission.audienceScore 字段

6.1.3 前端黑客松界面

1. 扩展 src/app/(public)/[locale]/events/[eventId]/EventDetailsClient.tsx

   • 在 event.type === "HACKATHON" 时渲染 <HackathonEventPage />

2. 新建黑客松专用组件

   src/modules/dashboard/events/components/hackathon/
   ├── HackathonEventPage.tsx       // 黑客松活动主页面
   ├── HackathonProjectSubmissionForm.tsx  // 项目提交表单
   ├── TeamMemberSelector.tsx       // 团队成员选择器
   ├── HackathonProjectGallery.tsx  // 项目展示画廊
   ├── VotingPanel.tsx             // 投票面板
   └── AwardShowcase.tsx           // 获奖展示组件

3. 团队成员管理

   • 复用 src/modules/dashboard/events/components/EventAdminManager.tsx 中的用户搜索功能
   • API 调用：/api/users/search?query=${query}

6.1.4 基础颁奖和证书

1. 复用现有 Award 系统 - 直接使用 src/server/routes/certificates.ts
2. 徽章自动发放 - 集成现有 Badge 系统
3. 基础证书生成 - 复用现有 CertificateTemplate 组件

第一阶段交付成果：

• ✅ 完整的黑客松活动页面（报名、提交、展示）
• ✅ 项目提交支持团队成员管理
• ✅ 观众投票和评委评分功能
• ✅ 自动颁奖和证书生成
• ✅ 基础的项目展示和反馈功能

6.2 第二阶段：增强功能（优化用户体验）

实施目标：增强功能和用户体验，完善生态

6.2.1 实时功能和数据展示

1. 投票结果展示

   • 新建 GET /api/events/:eventId/rankings API
   • 投票结果显示机制
   • 前端 useVotingResults Hook 实现

2. 活动状态管理

   • 基于 hackathonConfig 自动切换活动阶段
   • 显示活动进展（报名期、提交期、投票期、颁奖期）

6.2.2 项目反馈系统优化

1. 公开反馈功能

   • 复用现有 src/server/routes/comments.ts
   • 在项目展示页面集成 CommentSection 组件
   • 黑客松项目专用反馈界面设计

2. 学习成果展示模块

   • 基于 Project 表新增字段设计展示组件
   • LearningOutcomesSection 组件实现

6.2.3 用户体验优化

1. 移动端适配完善

   • 投票界面移动端优化
   • 项目展示画廊响应式设计
   • 团队成员管理移动端适配

2. 加载和交互优化

   • 项目提交流程用户体验优化
   • 投票反馈即时响应
   • 错误处理和提示完善

6.2.4 数据分析和运营工具

1. 活动数据统计面板

   • 参与度分析、投票数据统计
   • 项目分类和标签分析
   • 获奖分布统计

2. 项目反馈系统优化

   • ProjectAward 表优化
   • 获奖徽章发放功能

第二阶段交付成果：

• ✅ 投票结果展示和数据统计
• ✅ 完善的项目反馈和社区互动功能
• ✅ 优化的移动端体验
• ✅ 运营数据分析工具
• ✅ 项目反馈和社区互动功能

6.3 技术实现要点

第一阶段技术重点

• 最小化 Schema 变更 - 只增加必要字段，使用 JSON 存储配置
• API 复用优先 - 基于现有 event-projects.ts 和其他路由扩展
• 组件复用 - EventAdminManager 用户搜索、现有 Comment 系统、Certificate 系统
• 类型安全 - TypeScript + Zod 验证，确保 API 类型安全

第二阶段技术重点

• 实时数据处理 - 轮询机制优化、数据缓存策略
• 用户体验优化 - 响应式设计、加载状态管理、错误处理
• 数据统计分析 - 基于现有数据生成统计报告
• 性能优化 - 图片压缩、API 响应优化、前端渲染优化

7. 现有系统调研结果

7.1 可直接复用的核心组件

7.1.1 项目提交系统 ✅

• 文件：src/server/routes/event-projects.ts
• 现有功能：完整的 EventProjectSubmission CRUD API
• 关键端点：
  • POST /events/:eventId/submit-project - 项目提交
  • GET /events/:eventId/submissions - 获取提交列表
  • PUT /submissions/:submissionId - 更新提交
  • PUT /submissions/:submissionId/review - 评委评分
• 数据字段：已支持 judgeScore, audienceScore, finalScore

7.1.2 团队成员搜索组件 ✅

• 文件：src/modules/dashboard/events/components/EventAdminManager.tsx
• 现有功能：通过用户名/姓名搜索注册用户
• 搜索API：/api/users/search?query=${query}
• UI组件：完整的用户选择界面、Avatar展示
• 复用方案：可直接复用此组件实现团队成员管理

7.1.3 投票系统 ✅

观众投票：

• 文件：src/server/routes/projects.ts
• API：POST /projects/:id/like, DELETE /projects/:id/like
• 实现：ProjectLike 系统，需要与 audienceScore 字段同步

评委投票：

• 字段：EventProjectSubmission.judgeScore (Float)
• API：已集成在 /submissions/:id/review 端点中

7.1.4 颁奖和证书系统 ✅

• 文件：src/server/routes/certificates.ts
• 功能：
  • POST /projects/:projectId/awards - 单项颁奖
  • 批量生成证书支持
  • 完整的 Award 和 ProjectAward 数据模型
• 前端组件：
  • CertificateGallery.tsx - 证书展示
  • CertificateTemplate.tsx - 证书模板

7.1.5 徽章系统 ✅

• 文件：src/lib/database/prisma/queries/badges.ts
• 功能：
  • 支持稀有度（COMMON/RARE/EPIC/LEGENDARY）和颜色区分
  • awardBadge() - 颁发徽章
  • checkAndAwardAutoBadges() - 自动徽章
• 获奖徽章设计：统一使用徽章系统，简化实现

7.2 MVP功能完备性评估

结论：现有系统高度完备，MVP开发工作量极小，主要为前端UI适配。

7.3 核心数据扩展需求

7.3.1 必需的Schema变更

-- Project表扩展（黑客松特有字段）
ALTER TABLE "project" ADD COLUMN "githubUrl" TEXT;
ALTER TABLE "project" ADD COLUMN "slidesUrl" TEXT;  
ALTER TABLE "project" ADD COLUMN "inspiration" TEXT;
ALTER TABLE "project" ADD COLUMN "challenges" TEXT;
ALTER TABLE "project" ADD COLUMN "learnings" TEXT;
ALTER TABLE "project" ADD COLUMN "nextSteps" TEXT;

-- Event表扩展（黑客松配置）
ALTER TABLE "event" ADD COLUMN "hackathonConfig" JSONB;

-- 团队成员通过Project关联表管理，不需要在EventProjectSubmission中添加字段

7.3.2 UI路由分离设计

前端路由结构：

• 管理后台：/app/events/[eventId]/manage
• 用户前端：/[locale]/events/[eventId]

类型化UI组件：

// EventDetailsClient.tsx 中根据活动类型展示不同UI
function renderEventContent(event: Event) {
  switch (event.type) {
    case "HACKATHON":
      return <HackathonEventPage event={event} />
    case "BUILDING_PUBLIC":  
      return <BuildingPublicPage event={event} />
    default:
      return <DefaultEventPage event={event} />
  }
}

7.3.3 主要开发工作

1. 前端组件：黑客松专用的项目提交表单和展示组件
2. 配置系统：基于 hackathonConfig JSON 的动态配置
3. 投票集成：ProjectLike 与 audienceScore 的数据同步
4. 徽章配置：创建黑客松获奖徽章模板
5. UI类型分离：HackathonEventPage 组件开发

8. MVP+ 功能扩展设计

8.1 投票权限控制系统

技术方案：直接操作 EventProjectSubmission.audienceScore，避免扩展 ProjectLike 表

// 投票权限检查API
POST /api/events/:eventId/submissions/:submissionId/vote
{
  voteType: 'AUDIENCE' | 'JUDGE',
  score?: number // 评委投票时提供1-10分
}

// 权限控制逻辑
async function checkVotingPermission(eventId: string, userId: string, voteType: string) {
  const config = event.hackathonConfig.voting
  
  if (voteType === 'AUDIENCE') {
    switch (config.publicVotingScope) {
      case 'ALL': return true
      case 'REGISTERED': return await isRegisteredUser(userId)  
      case 'PARTICIPANTS': return await isEventParticipant(eventId, userId)
    }
  }
  // 评委权限检查...
}

8.2 项目反馈系统设计

设计决策：采用公开反馈模式，复用现有 Comment 系统

优势分析：

• ✅ 促进社区学习和讨论
• ✅ 提高透明度和参与感
• ✅ 技术实现简单，复用现有功能
• ✅ 私密反馈可通过微信等私下交流

实现方案：

// 黑客松项目反馈展示
const HackathonProjectFeedback = ({ projectId, eventId }) => {
  return (
    <Card>
      <CardHeader>💬 社区反馈</CardHeader>
      <CardContent>
        <CommentSection 
          entityType="PROJECT" 
          entityId={projectId}
          placeholder="给这个项目一些建设性反馈吧..." 
          context={{ eventId, isHackathon: true }}
        />
      </CardContent>
    </Card>
  )
}

8.3 投票结果展示

实现方案：按需加载 + 缓存优化

// API端点
GET /api/events/:eventId/rankings
{
  submissions: [
    {
      id: string,
      title: string, 
      judgeScore: number,
      audienceScore: number,
      finalScore: number,
      rank: number
    }
  ],
  lastUpdated: timestamp
}

// 前端结果显示
const useVotingResults = (eventId: string) => {
  const [rankings, setRankings] = useState([])
  
  const fetchResults = useCallback(async () => {
    const response = await fetch(`/api/events/${eventId}/rankings`)
    if (response.ok) {
      const data = await response.json()
      setRankings(data.submissions)
    }
  }, [eventId])
  
  return { rankings, fetchResults }
}

8.4 前端项目展示页面

位置：在 /[locale]/events/[eventId] 中增加"参赛项目"标签页

const HackathonProjectsTab = ({ eventId }) => {
  return (
    <div className="space-y-6">
      {/* 投票结果展示 */}
      <RankingBoard eventId={eventId} />
      
      {/* 项目展示网格 */}
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
        {submissions.map(submission => (
          <HackathonProjectCard 
            key={submission.id}
            submission={submission}
            showVoting={canVote}
            showFeedback={true}
            eventId={eventId}
          />
        ))}
      </div>
    </div>
  )
}

8.5 学习成果展示模块

实现：基于已规划的 Project 表黑客松字段

const LearningOutcomesSection = ({ project }) => (
  <Card className="mt-6">
    <CardHeader>
      <CardTitle className="flex items-center gap-2">
        🎯 学习成果分享
      </CardTitle>
    </CardHeader>
    <CardContent className="space-y-4">
      {project.inspiration && (
        <LearningItem icon="💡" title="灵感来源" content={project.inspiration} />
      )}
      {project.challenges && (
        <LearningItem icon="⚡" title="技术挑战" content={project.challenges} />
      )}
      {project.learnings && (
        <LearningItem icon="🚀" title="学习收获" content={project.learnings} />
      )}
      {project.nextSteps && (
        <LearningItem icon="📋" title="下一步计划" content={project.nextSteps} />
      )}
    </CardContent>
  </Card>
)

8.6 MVP+ 实现优先级

1. 高优先级 - 第二版本（1-2周）：

   • 项目公开反馈系统
   • 前端项目展示页面
   • 投票权限控制API

2. 中优先级 - 第三版本（2-4周）：

   • 投票结果展示
   • 评委专用评分界面
   • 学习成果展示优化

3. 低优先级 - 后续版本：

   • 活动数据统计面板
   • 社区互动功能增强

本文档基于现有系统深度调研，确保通过最小改动实现完整的黑客松功能。现有系统的高完备度使得MVP开发成本极低。