ggdude-sudo/kaspa-Learn
GitHub: ggdude-sudo/kaspa-Learn
一个基于 Kaspa 区块链的互动式学习平台，通过 CTF 风格的挑战和钱包认证机制，提供游戏化的知识问答与等级成长体验。
Stars: 0 | Forks: 0
# KaspaLearn - 技术文档
一个游戏化的 Kaspa 区块链学习平台，用户可以通过解决挑战、回答问题来赚取 XP 和徽章。
## 目录
- [设置](#setup)
- [架构概览](#architecture-overview)
- [钱包认证](#wallet-authentication)
- [数据库模式](#database-schema)
- [功能模块](#feature-modules)
- [排行榜与挑战](#leaderboard--challenges)
- [问题添加与导入](#question-add--import)
- [管理面板](#admin-panel)
- [环境变量](#environment-variables)
- [路由](#routing)
## 设置
### 前置条件
- Node.js 18+
- Supabase 项目
- Kaspa 钱包（用于身份验证）
### 安装
```
npm install
```
### 环境变量
在根目录下创建一个 `.env` 文件：
```
VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
```
### 开发
```
npm run dev
```
### 构建
```
npm run build
```
## 架构概览
```
src/
├── components/ # Reusable UI components
│ ├── auth/ # Login, Signup, Auth components
│ ├── gamification/ # Level badges, achievements
│ └── ui/ # Base UI (Button, Card, Input, etc.)
├── context/ # React context providers
│ ├── AuthContext.tsx # Wallet authentication state
│ └── ThemeContext.tsx# Dark/light theme
├── features/ # Main page components
│ ├── Leaderboard.tsx # Leaderboard display
│ ├── ChallengeList.tsx
│ ├── ChallengeDetail.tsx
│ ├── Questions.tsx # Q&A section
│ ├── AdminPanel.tsx # Admin management
│ └── DevPanel.tsx # Developer tools
├── services/ # Business logic
│ ├── challengeService.ts
│ └── badgeService.ts
├── supabaseClient.ts # Database client & wallet auth
├── App.tsx # Routes & app structure
└── index.tsx # Entry point
```
## 钱包认证
认证通过 Supabase Edge Functions 使用 Kaspa 钱包地址完成。
### 文件
- `src/supabaseClient.ts` - 主要认证逻辑
- `src/context/AuthContext.tsx` - 认证状态管理
- `src/components/auth/Login.tsx` - 登录界面
### 工作原理
1. 用户输入他们的 Kaspa 钱包地址
2. 应用调用 `initSupabaseWithWallet(walletAddress)`
3. Supabase edge function (`wallet-auth`) 验证地址并返回一个 JWT
4. JWT 存储在 localStorage 中，用于后续请求
5. 在 `profiles` 表中创建/更新用户配置文件
### Profile 表
```
profiles (
id uuid PK
username text UNIQUE
wallet_address text UNIQUE
role text DEFAULT 'user' -- 'user', 'mod', 'admin', 'dev'
xp integer DEFAULT 0
level integer DEFAULT 1
challenges_solved integer DEFAULT 0
first_bloods integer DEFAULT 0
created_at timestamptz
updated_at timestamptz
)
```
## 数据库模式
### 主要数据表
| 数据表 | 描述 |
| --------------------- | -------------------------- |
| `profiles` | 用户账户与统计数据 |
| `challenges` | 挑战定义 |
| `challenge_questions` | 挑战中的问题 |
| `challenge_flags` | CTF 风格的 flag |
| `user_progress` | 已完成的挑战 |
| `user_answers` | 问题回答 |
| `categories` | 挑战分类 |
| `difficulty_levels` | 难度设置 |
| `levels` | 玩家等级 |
| `badges` | 成就定义 |
| `user_badges` | 已获得的徽章 |
| `xp_history` | XP 交易日志 |
### 核心数据表详情
#### 挑战
```
challenges (
id uuid PK
title text
description text
category_id uuid FK
difficulty_id uuid FK
xp_reward integer
solves_count integer DEFAULT 0
is_active boolean DEFAULT true
is_retired boolean DEFAULT false
creator_id uuid FK -> profiles.id
creator_notes text
created_at timestamptz
)
```
#### challenge_questions
```
challenge_questions (
id uuid PK
challenge_id uuid FK -> challenges.id
question_type text -- 'mcq', 'fib', 'single_choice'
question_text text
options jsonb -- for MCQ
correct_answer text
explanation text
hint text
order_index integer
points integer
)
```
#### 分类
```
categories (
id uuid PK
name text
display_name text
description text
icon text -- emoji
color text -- hex color
)
```
## 功能模块
### 排行榜与挑战
**文件：**
- `src/features/Leaderboard.tsx` - 排行榜 UI
- `src/services/challengeService.ts` - 挑战逻辑
- `src/features/ChallengeList.tsx` - 挑战列表
- `src/features/ChallengeDetail.tsx` - 挑战页面
**工作原理：**
1. 排行榜从 `profiles` 表中获取按 XP 排序的顶级用户
2. 挑战列表带有分类/难度过滤器
3. 用户提交答案以获取 XP
4. 首位解决者（一血）会获得额外荣誉
**核心函数 (challengeService.ts)：**
```
// Get all challenges with filters
challengeService.getChallenges(filters);
// Get leaderboard ranking
challengeService.getLeaderboard(limit);
// Submit answers and earn XP
challengeService.submitAnswers(userId, challengeId, answers);
// Get first blood leaders
challengeService.getFirstBloodLeaders(limit);
```
**等级系统：**
| 等级 | XP 范围 | 称号 |
| ---- | --------- | ------------ |
| 1 | 0-99 | Beginner |
| 2 | 100-299 | Novice |
| 3 | 300-599 | Intermediate |
| 4 | 600-999 | Advanced |
| 5 | 1000-1999 | Expert |
| 6 | 2000+ | Master |
### 问题添加与导入
**文件：**
- `src/features/Questions.tsx` - 问答界面
- `src/features/DevPanel.tsx` - 开发者面板
**添加问题 (Questions.tsx)：**
1. 导航到问题页面
2. 填写问题表单：
- 问题文本
- 选项（用于 MCQ）
- 正确答案
- 解释
- 分类
- 难度
3. 点击 "Add Question"
4. 管理员：问题会进入 `modules_pending` 表
5. 普通用户：保存到 localStorage
**开发者面板 (DevPanel.tsx)：**
- 创建包含多个问题的新挑战
- 从 JSON 导入问题
- 提交挑战以待批准
- 编辑自己的提交
**问题类型：**
- `mcq` - 多项选择（4个选项）
- `fib` - 填空题
- `single_choice` - 是/否或真/假
**导入格式：**
```
{
"questions": [
{
"question_text": "What is Kaspa?",
"options": ["Option A", "Option B", "Option C", "Option D"],
"correct_answer": "Option A",
"explanation": "Kaspo explanation..."
}
]
}
```
### 管理面板
**文件：** `src/features/AdminPanel.tsx`
**功能：**
- 管理用户（提升/降低角色）
- 批准/拒绝挑战
- 查看待处理的提交
- 审核内容
- 查看统计数据
**角色：**
| 角色 | 权限 |
| ------- | ---------------------------------- |
| `user` | 解决挑战，获取 XP |
| `dev` | 创建挑战，提交以待批准 |
| `mod` | 批准内容，管理用户 |
| `admin` | 完全访问权限，系统设置 |
## 环境变量
| 变量 | 描述 | 是否必须 |
| ----------------------- | ----------------- | -------- |
| `VITE_SUPABASE_URL` | Supabase 项目 URL | 是 |
| `VITE_SUPABASE_ANON_KEY` | Supabase anon key | 是 |
从你的 Supabase 项目设置 > API 中获取这些信息。
## 路由
| 路由 | 组件 | 访问权限 |
| -------------------- | --------------- | ------------- |
| `/` | Home | 公开 |
| `/challenges` | ChallengeList | 公开 |
| `/challenges/:id` | ChallengeDetail | 公开 |
| `/leaderboard` | Leaderboard | 公开 |
| `/login` | Login | 公开 |
| `/dashboard` | Dashboard | 需认证 |
| `/profile` | Profile | 需认证 |
| `/profile/:username` | PublicProfile | 公开 |
| `/questions` | Questions | 需认证 |
| `/admin` | AdminPanel | Admin/Mod |
| `/dev` | DevPanel | Dev/Admin/Mod |
## 技术栈
- **前端：** React, TypeScript, Vite
- **样式：** Tailwind CSS, Radix UI
- **数据库：** Supabase (PostgreSQL)
- **钱包：** Kaspa (通过 @kasplex/KaspaTS)
- **状态管理：** React Context, localStorage
## 许可证
MIT
标签：BaaS, DApp, EdTech, GNU通用公共许可证, IP 地址批量处理, Kaspa, MITM代理, Node.js, PostgreSQL, React, SPA, Supabase, Syscalls, TypeScript, Vite, Web3, XP, 加密货币, 区块链, 升级, 单页应用, 去中心化, 威胁情报, 学习平台, 安全插件, 开发者工具, 徽章, 成就系统, 挑战赛, 排行榜, 教育科技, 暗色模式, 游戏化, 用户体验, 管理后台, 经验值, 自动化攻击, 解谜, 钱包认证, 问答系统, 题库导入