OpenHackathon

开源黑客松全流程管理平台 · Open Source Hackathon Management Platform

从赛事创建到排行榜发布，一站式管理黑客松

核心功能 • 界面导览 • 架构 • 快速开始 • 部署

简体中文 | English

📖 项目简介

OpenHackathon 是面向黑客松主办方、评委与参赛团队的全流程管理平台，覆盖从赛事创建、项目提交、评审分配、打分评审到排行榜发布的完整链路。

平台提供三套独立入口：

参赛者（公开访问）：浏览赛事首页、提交项目、查看排行榜
管理员（/admin/login）：管理赛事配置、项目、评委、评审分配、排行榜、站点设置
评委（/judge/login）：查看分配的评审任务、打分、提交评语

全站支持 中英文双语实时切换、深浅主题切换、字体大小与字体族调整，并已接入 Web3 钱包登录与跨赛事积分。

✨ 核心功能

1. 公开赛事页面

参赛者无需登录即可浏览当前赛事：

赛事名称、标语、状态徽章（Draft / Upcoming / Active / Judging / Completed）
举办城市、日期范围、奖金池
倒计时组件与提交入口
响应式深浅主题适配

2. 项目提交与回执

表单字段完全由主办方在后台配置
内置字段：项目名称（必填）、邮箱（必填）、姓名（选填）
提交后自动生成回执号（如 SUB-20260228-ABC123）
支持 SMTP 自动发送确认邮件

3. 管理后台

登录后进入仪表盘，左侧侧边栏按功能域分组：

Hackathon：Projects / Assignments / Leaderboard
Judges：Judge Management
Settings：Hackathon Settings / Activity Log / Site Settings / AI Features

4. 评审分配与评分

随机 / 手动分配评委到项目
实时统计：Total Projects、Average Score、Completion Rate、Judges
列表视图与矩阵视图
评分标准由管理员自定义，总分必须恰好为 100 分

5. AI 增强系统（v2.2）

智能化赋能每个角色，6 大能力 6 个 tab 集中管理：

🤖 项目质量评估：AI 自动分析项目，生成 0-100 分评分 + 4 维度详情（完整性 / 创新性 / 技术深度 / 呈现质量），支持单项目评估 + 批量分析（5 并发池 + 实时进度跟踪）
🎯 评委智能助手：评审时提供 AI 建议、项目摘要、关键技术点、评分参考
📊 评分一致性分析：实时监控评委评分偏差，识别过严/过宽评委（AI suggestion 并发执行，10 评委从 30s 降到 ~3s）
🛡️ 内容审核：自动检测敏感内容、垃圾信息、仇恨言论（5 类 flag + 3 档严重度 + 建议操作 approve/review/reject）
✍️ 智能内容生成：一键生成 README、优化项目描述、Pitch Deck 大纲、新闻稿、邮件、评分标准（6 type × 2 language × 4 style = 48 种组合）
🔍 抄袭检测：两段文本对比 / 同赛事项目 pairwise 对比（>70% 高风险 / 30-70% 中风险 / <30% 低风险）

支持 Claude (Anthropic)、OpenAI、DeepSeek、本地 Ollama 等多种 AI 提供商。

v2.2 核心改进

✅ 6 个 tab 覆盖全部 AI 能力（之前只有 4 个，缺抄袭检测和 AI 运行状态）
✅ 5 类错误分类 UX（network / unauthorized / forbidden / server / timeout），不暴露内部 stack / API key
✅ batch 任务进度跟踪（实时轮询 + 进度条 + 失败项目列表，taskId 不再是孤儿）
✅ fetch 30s 超时 + 错误脱敏（上游 hang 不再拖死 server）
✅ i18n 全覆盖（zh + en 双语，21 个 page 唯一缺失补齐）
✅ fetch timeout + 输入截断（防恶意 payload 烧 token）
✅ AI Metrics 可视化（admin 直接看 calls / errors / duration / provider 分布）

详细文档

📖 AI_FEATURES_CHANGELOG.md — v2.1 → v2.2 完整改动历史
🎨 AI_FEATURES_UX.md — 6 tab UX 设计 + 用户故事 + 错误分类规则
🔌 AI_FEATURES_API.md — 11 个 API 端点完整文档
👥 USER_GUIDE_AI.md — 给最终用户看的使用指南（admin / 评委 / 参赛者）

快速配置

# .env 文件中配置 AI（任选其一）
AI_PROVIDER=claude                                    # claude / openai / local
AI_API_KEY=sk-ant-your-key-here                       # Anthropic API key
AI_MODEL=claude-sonnet-4-20250514                     # 可选，留空用 provider 默认
# AI_BASE_URL=https://api.anthropic.com/v1             # 可选，留空用 provider 默认

进入 admin 后台 → AI 功能控制台（/admin/ai-features）即可看到 6 个 tab，无需命令行。

6. Web3 多链身份与积分

🔗 钱包登录：基于 RainbowKit + wagmi，支持 EVM 钱包通过 SIWE 登录
🏆 跨赛事积分：Web3 用户拥有全局积分、参赛次数、评审次数、获奖次数
🌐 跨赛事排行榜：Global Leaderboard 展示全平台用户排名
👤 个人资料页：展示钱包地址、积分历史、参与记录
⛓️ 可选链上证明：管理员可将关键数据写入链上作为可验证证明（可选）

7. 外观与无障碍

🌙 浅色 / 深色 / 跟随系统三种主题模式
🔤 字体大小：Small / Normal / Large
🖋️ 字体族：Geist / System UI
♿ 语义化颜色、高对比度、键盘可访问

8. 品牌白标与站点设置

自定义站点名称、Logo、Favicon、浏览器标签标题
SEO 标题与描述
页脚 Powered By 文案与链接
自定义管理后台入口路径（adminBasePath）

🖼️ 界面导览

公开首页	项目提交	公开排行榜

管理员登录	评委登录	管理仪表盘

项目管理	评审分配	评委管理

赛事设置	提交表单配置	评分标准

排行榜管理	操作日志	站点设置

AI 功能中心	评委工作台

🏛️ 架构

技术栈

层	技术
前端	React 18 + Vite + TailwindCSS + shadcn/ui + React Query + react-i18next
后端	Express.js + Prisma ORM + PostgreSQL
Web3	wagmi + RainbowKit + viem + Solana Wallet Adapter
测试	Vitest（单元 + API）+ Playwright（E2E）
部署	GitHub Actions → PM2 + Nginx

后端模块化架构

api/
├── server.ts          # Express 应用入口
├── config.ts          # 环境变量与常量
├── middleware.ts      # JWT 认证、角色鉴权、速率限制
├── routes/            # 路由模块
│   ├── auth.ts        # 登录/注册（admin + judge 独立）
│   ├── hackathons.ts  # 赛事 CRUD
│   ├── projects.ts    # 项目提交、编辑、删除
│   ├── assignments.ts # 评审分配
│   ├── scores.ts      # 评分提交
│   ├── judges.ts      # 评委管理
│   ├── ai.ts          # AI 功能 API
│   ├── web3-auth.ts   # Web3 钱包登录
│   ├── identity.ts    # 跨赛事身份与积分
│   ├── leaderboard.ts # 排行榜管理
│   ├── site-settings.ts # 站点设置
│   └── ...
└── services/          # 业务服务
    ├── ai.ts          # AI 服务
    ├── identity.ts    # Web3 身份服务
    ├── points.ts      # 积分服务
    └── onchain.ts     # 链上交互

安全机制

机制	说明
JWT 认证	admin / judge 独立令牌，支持 issuer/audience 校验
输入校验	全字段白名单校验 + 长度限制 + SQL 注入/XSS 关键词过滤
速率限制	全局 1200/15min + 登录 20/15min + 提交 30/10min
CORS	支持逗号分隔域名白名单
文件上传	类型/大小白名单 + 文件名安全过滤

🚀 快速开始

环境要求

Node.js 20+
Docker + Docker Compose

一键启动

git clone https://github.com/frankfika/openhackathon.git
cd openhackathon
npm install
npm run dev:up

自动完成：启动 PostgreSQL → 等待数据库就绪 → 同步 Prisma schema → 启动前后端开发服务。

首次访问会进入 Setup Wizard（/setup），引导创建管理员账号和初始赛事。

常用命令

npm run dev:up         # 启动开发栈（不含 seed 数据）
npm run dev:up:seed    # 启动开发栈 + 写入演示数据
npm run dev:down       # 关闭数据库容器
npm run db:reset:seed  # 重置 + 写入演示数据
npm run dev            # 仅启动前后端（需自行管理数据库）

默认账号（seed 数据）

角色	邮箱	密码
管理员	`admin@openhackathon.com`	`password`
评委	`alice@techgiants.com`	`password`
评委	`bob@venturecap.com`	`password`
评委	`charlie@designstudio.io`	`password`
空评委	`judge1@openhackathon.com`	`password`

AI 功能配置（可选）

AI 增强系统（项目评估、内容审核、智能生成等）需要配置 API key 才能工作。不配置也能启动项目，只是 AI 相关功能会返回"AI service error"。

.env 中任选一种 provider：

# Claude (Anthropic) — 推荐
AI_PROVIDER=claude
AI_API_KEY=sk-ant-api03-your-key-here

# OpenAI
AI_PROVIDER=openai
AI_API_KEY=sk-your-openai-key-here

# 本地 Ollama (无 key，免费)
AI_PROVIDER=local
# AI_API_KEY 留空
# AI_BASE_URL=http://localhost:11434/v1

配置后到 /admin/ai-features 即可使用 6 个 AI tab。详细文档见 AI_FEATURES_API.md。

🧪 测试

npm run test:unit      # 单元测试（Vitest）
npm run test:api       # API 集成测试
npm run test:storybook # Storybook 组件测试
npm run test:e2e       # E2E 端到端测试（Playwright）
npm run lint           # ESLint 检查
npx tsc --noEmit       # TypeScript 类型检查

🏗️ 部署

在线演示

体验地址：http://49.234.25.35

一键部署（Ubuntu）

curl -fsSL https://raw.githubusercontent.com/frankfika/openhackathon/main/scripts/deploy-server.sh | bash

自动部署（CI/CD）

推送到 main 分支后 GitHub Actions 自动部署：

git push origin main

Docker Compose

docker compose up -d --build

默认端口：

服务	端口
Web	`5173`
API	`3001`
PostgreSQL	`5432`
Adminer	`8080`

📸 截图脚本

所有 README 截图均从真实运行的应用截取：

npm run dev
node scripts/capture-screenshots.mjs

📝 更新日志

v2.2 (2026-07)

AI 增强系统全面重做

🔧 修复 v2.1 上线时埋的真 bug：zod v3→v4 升级后 _def.shape() API 变了，导致 v2.1 schema 模式 100% 静默 fallback — analyzeProject 永远返回默认 50 分，moderateContent 永远返回"需要 review"。AI 检测 v2.1 实际上从未真工作过，这次彻底修复（重写 zodToJsonSchema 支持 v4 完整 API）
🎨 AIFeatures UI 全面重做：从 4 tabs → 6 tabs（新增抄袭检测 + AI Metrics），每个 tab 都有 loading / empty / error / success 4 态
📊 batch 任务进度跟踪：之前 taskId 是孤儿（返回后没地方查），现在新增 GET /api/ai/batch-status/:taskId endpoint + 前端 2s 轮询 + 进度条 + 失败项目列表
🛡️ 5 类错误分类 UX（network / unauthorized / forbidden / server / timeout），不暴露内部 stack / API key 痕迹
⏱️ fetch 30s 超时（AbortController），上游 hang 不再拖死 server
🌍 i18n 全覆盖（zh + en 双语），是 21 个 page 里唯一缺失 useTranslation 的 AIFeatures，现在补齐
⚡ 并发执行：analyzeScoringConsistency（10 评委 30s → 3s）、check-plagiarism pairwise、batch-analyze 5 并发池
📈 AI Metrics 可视化：新增 GET /api/ai/metrics endpoint + 第 6 个 tab，admin 可看 calls / errors / duration / provider 分布
🧪 36 个单测 + 9 个 e2e（api/__tests__/ai.test.ts + e2e/ai-features.spec.ts）
📖 3 个 AI 文档（docs/AI_FEATURES_{CHANGELOG,UX,API}.md）

安全与稳定

🔒 安全加固：修复 8 处密码哈希泄露漏洞。/api/projects/:id（公开端点，无鉴权）和 7 个 admin/judge 端点此前通过 Prisma 的 include: { judge: true } / user: true 把整张 User 行返回给前端，包括 password bcrypt 哈希。已全部改为显式 select 白名单字段（id, email, name, role, avatarUrl, createdAt），保留全字段的 auth.ts / web3-auth.ts 仍走 sanitizeUser 兜底。
🛣️ 管理后台补全路由：/admin/activity（操作日志）和 /admin/account（账户设置）此前路由外壳已声明但 lazy() import 未接，现在可正常访问 ActivityLogPage / Account 页面。
🩹 状态显示同步：公共 header 状态徽章与 hero badge 现在统一在 endAt 过零点时显示 Completed（之前会继续显示 ACTIVE 直到管理员手动改 status 字段）。
🩹 JudgingDetail 表单初始化：评分页现在等 assignment 和 hackathon（含 scoringCriteria）双双加载完才挂载，避免首屏空 ScoreDraft 导致分数输入框看起来是空的。
🩹 judge logout 按钮：补 type="button"，避免在某些父级表单里被当成 submit 误触发。
🛠️ 代码优化：JudgingDetail 把"初始回填分数"从 useEffect 挪到 useState 的 lazy initializer，只在 assignment?.id 变化时同步 comment，避免初次挂载时的"空 → 回填"闪烁。

v2.1 (2026-06)

✨ AI 增强系统：项目质量评估、评委助手、评分一致性分析、内容审核、智能生成、抄袭检测
🔗 Web3 多链身份：钱包登录、跨赛事积分、全球排行榜、链上可选证明
🎨 外观设置：主题切换、字体大小/字体族调整
🐛 修复深色主题与悬浮导航重叠等视觉细节

v2.0 (2026-03)

🏆 完整黑客松管理流程上线
🌐 中英双语、深浅主题
📊 评审分配、评分、排行榜管理
🛡️ JWT 认证、速率限制、操作日志

📦 发布

Releases: https://github.com/frankfika/openhackathon/releases

📄 License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 79 Commits
.claude		.claude
.edgeone		.edgeone
.github		.github
.storybook		.storybook
api		api
content		content
contracts		contracts
docs		docs
e2e		e2e
examples		examples
prisma		prisma
public		public
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
Dockerfile.api		Dockerfile.api
Dockerfile.web		Dockerfile.web
README.md		README.md
README_EN.md		README_EN.md
audit-AI-UX-2026-07-19.md		audit-AI-UX-2026-07-19.md
audit-launch-2026-08-06.md		audit-launch-2026-08-06.md
components.json		components.json
dev-eval-5181.sh		dev-eval-5181.sh
dev-eval.sh		dev-eval.sh
dev-stack.sh		dev-stack.sh
docker-compose.yml		docker-compose.yml
eslint.config.js		eslint.config.js
hardhat.config.cjs		hardhat.config.cjs
index.html		index.html
nodemon.json		nodemon.json
package-lock.json		package-lock.json
package.json		package.json
performance-audit-2026-07-24.md		performance-audit-2026-07-24.md
playwright.config.ts		playwright.config.ts
postcss.config.js		postcss.config.js
prisma.config.ts		prisma.config.ts
progress-launch-sprint-3.5.md		progress-launch-sprint-3.5.md
render.yaml		render.yaml
security-audit-2026-07-24.md		security-audit-2026-07-24.md
seed-dev.ts		seed-dev.ts
synthesis-launch-2026-08-06.md		synthesis-launch-2026-08-06.md
tailwind.config.js		tailwind.config.js
test-ui-screenshots.mjs		test-ui-screenshots.mjs
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts
vitest.config.api.ts		vitest.config.api.ts
vitest.config.ts		vitest.config.ts
vitest.shims.d.ts		vitest.shims.d.ts

Folders and files

Latest commit

History

Repository files navigation