# ETHGlobal Taipei - 發文平台 Spec 詳細規格文件
本規格文件描述一個類似 Reddit 的開放討論平台，平台將採用 Next.js 作為前後端框架，Supabase 作為資料庫及部分驗證服務（例如 Supabase Auth），區塊鏈部分則選擇 CELO 來實現獎勵機制與智能合約功能。平台主打匿名與半匿名發文、身份屬性認證以及針對內容互動的 Web3 激勵系統。
---
## Architecture Diagram
以下使用 Mermaid 畫出整體系統架構圖：
```mermaid
graph LR
subgraph FE[Frontend]
A[Next.js]
end
subgraph BE[Backend API]
B[Next.js]
end
subgraph DB[Database]
C[Supabase]
end
subgraph VER[Verification Services]
E[Self Verification Service]
end
subgraph BC[Blockchain]
F[CELO Blockchain]
end
A --> B
A -- "FrontendKit" --> E
E -- "QR Code" --> A
B -- "BackendKit" --> E
E -- "OnchainKit" --> F
E --> C
C --> F
```
---
## 1. 產品概述
本平台提供一個跨國界的地球村社群環境，允許用戶透過加密錢包登入，並可藉由 Self 護照屬性認證來選擇性公開個人資訊。用戶可在發文時設定「allowed_viewers」與「allowed_commenters」條件，從而限制誰可以查看或評論該文章。平台還會整合 CELO 區塊鏈，對高互動或優質內容進行獎勵，透過智能合約發放代幣或 NFT 獎章。
---
## 2. 技術架構
* **前後端框架**：使用 Next.js 建構 SSR 與 API Routes，統一前後端程式碼，提高開發效率。
* **資料庫與驗證**：採用 Supabase（基於 PostgreSQL）同時驗證服務Self
* **區塊鏈整合**：選用 CELO 區塊鏈來部署獎勵相關的智能合約，確保獎勵發放透明且可驗證並直接與 proof 互動
---
## 3. 功能模組
### 3.1 用戶驗證與註冊
#### 加密錢包登入 (RainbowKit)
用戶透過連接加密錢包登入平台：
* 使用RainbowKit的Connect Wallet功能提供多種錢包連接選項
* 錢包連接後，系統自動檢查該錢包地址是否已存在於用戶表中
* 若不存在，則創建新用戶記錄，設置默認Display Name
* 若已存在，則直接登入並載入用戶信息
#### 用戶個人資料管理
* 用戶可以修改自己的Display Name，便於在平台中被識別
* 個人資料頁面顯示用戶的發文歷史、獲得的獎勵等信息
#### Self 護照屬性認證
用戶在發文或留言時可啟用 Self 驗證流程：
* 前端展示 QR Code，由用戶掃描後獲取護照屬性（如 Issuing State、Passport Number、Name、Gender、Nationality、Expiry Date、Date of Birth）。
* 驗證結果回傳並可用於設定文章的瀏覽和評論權限。
### 3.2 發文功能
#### 匿名/半匿名發文
用戶可選擇完全匿名或附帶部分身份資訊進行發文。
#### 自定義文章訪問與評論限制
發文者可在發文時設定：
* **allowed_viewers**：例如限制只允許特定國籍或年齡以上的用戶查看文章。
* **allowed_commenters**：只有通過指定身份認證（例如 Self 驗證並公開特定屬性）的用戶才能留言。
#### 內容互動
包含 Like/Dislike、圖片附件、表情符號等互動元素。
### 3.3 評論與即時互動
* 僅允許符合 allowed_commenters 條件的用戶對文章進行評論。
* 使用 Next.js API Routes 與 Supabase 的即時功能（Realtime）或 WebSocket 實現評論與點讚的即時更新通知。
### 3.4 獎勵機制 (Web3 與 CELO 整合)
#### 獎勵代幣發放
當文章達到特定讚數或達成指定互動門檻時，自動透過智能合約調用 CELO 區塊鏈發放獎勵代幣給發文者或特定評論者（例如首條評論）。
#### NFT 獎章
對於活躍或優質內容創作者，鑄造 NFT 獎章作為榮譽認證。
#### DAO 治理
獎勵代幣持有者可以參與平台治理，包括內容審核、功能投票與激勵標準調整。
---
## 4. Supabase 資料庫 Schema 設計
以下針對 Supabase（PostgreSQL）直接設計各主要 Table Schema，並附上建表 SQL 範例。
### 4.1 用戶與身份驗證相關
**Users Table** - 儲存用戶基本資訊和錢包地址
```sql
CREATE TABLE IF NOT EXISTS users (
user_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
wallet_address VARCHAR(255) UNIQUE NOT NULL,
display_name VARCHAR(100),
avatar_url VARCHAR(255),
created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc', now()),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc', now())
);
```
### 4.2 文章與評論相關
**Posts Table** - 儲存所有發布的文章內容和權限設定
```sql
CREATE TABLE IF NOT EXISTS posts (
post_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES users(user_id) ON DELETE SET NULL,
title VARCHAR(255),
content TEXT,
anonymity_flag BOOLEAN DEFAULT false,
allowed_viewers JSONB, -- 例如 {"nationality": "Taiwan", "min_age": 20}
allowed_commenters JSONB, -- 設定評論條件
likes_count INTEGER DEFAULT 0,
created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc', now()),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc', now()),
reward_enabled BOOLEAN DEFAULT false,
reward_type INTEGER,
reward_contract VARCHAR(255)
);
```
**Comments Table** - 儲存文章下所有評論
```sql
CREATE TABLE IF NOT EXISTS comments (
comment_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
post_id UUID REFERENCES posts(post_id) ON DELETE CASCADE,
user_id UUID REFERENCES users(user_id) ON DELETE SET NULL,
content TEXT,
likes_count INTEGER DEFAULT 0,
created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc', now()),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc', now())
);
```
**Likes Table** - 記錄用戶對文章或評論的點讚
```sql
CREATE TABLE IF NOT EXISTS likes (
like_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
user_id UUID REFERENCES users(user_id) ON DELETE CASCADE,
target_id UUID, -- 可指向 posts 或 comments
target_type VARCHAR(20), -- "Post" 或 "Comment"
created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc', now())
);
```
### 4.3 獎勵與交易相關 (Web3 - CELO)
**Rewards Table** - 記錄所有透過智能合約發放的獎勵資格
```sql
CREATE TABLE IF NOT EXISTS rewards (
reward_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
post_id UUID REFERENCES posts(post_id) ON DELETE CASCADE, -- 關聯到特定文章
user_id UUID REFERENCES users(user_id) ON DELETE CASCADE, -- 獎勵獲得者
reward_type INTEGER NOT NULL, -- 1:給第一個留言者Token獎勵, 2:每個留言者獲得NFT
status VARCHAR(20) DEFAULT 'pending', -- pending, claimed, failed
created_at TIMESTAMP WITH TIME ZONE DEFAULT timezone('utc', now())
);
-- 為post_id和user_id組合創建唯一索引，確保每個用戶只能獲得一次特定文章的獎勵
CREATE UNIQUE INDEX rewards_post_user_idx ON rewards (post_id, user_id);
```
**獎勵類型說明:**
1. **Type 1 - 首評獎勵**: 給予文章的第一個留言者Token獎勵，每篇文章只會產生一筆此類獎勵
2. **Type 2 - 參與NFT**: 每個對文章留言的人都可獲得一個NFT，每個用戶每篇文章僅能獲得一次
---
## 5. 交互流程設計
### 5.1 用戶註冊與驗證流程
#### 登入流程 (RainbowKit)
1. 用戶進入平台，點擊Connect Wallet按鈕
2. RainbowKit顯示支持的錢包選項（如MetaMask, Coinbase Wallet等）
3. 用戶選擇並連接錢包
4. 前端獲取用戶的錢包地址，並發送到後端
5. 後端檢查該錢包地址是否已存在於users表中：
* 若不存在，創建新用戶記錄，設置初始Display Name（可用錢包地址縮寫）
* 若已存在，載入該用戶資料
6. 返回登入成功訊息和用戶資料
#### 用戶資料更新
1. 用戶可在個人資料頁修改Display Name
2. 前端將修改發送至後端API
3. 後端更新users表中相應記錄
4. 返回更新成功訊息和最新用戶資料
#### 身份屬性驗證 (Self)
* 用戶在進行發文或留言前選擇啟用 Self 驗證。
* 前端展示 QR Code，由用戶掃描後觸發驗證請求至 Self 驗證服務。
* 驗證數據僅用於即時權限判斷，不長期存儲在數據庫中。
### 5.2 發文流程
1. 用戶在 Next.js 前端點擊「發文」，進入文章創建頁面。
2. 用戶填寫標題與內容，並選擇是否匿名（設置 anonymity_flag）。
3. 發文者設定 allowed_viewers 與 allowed_commenters 條件（以 JSON 格式儲存）。
4. 若需要進一步身份驗證，啟動 Self QR Code Proof 流程。
5. 文章數據經由 Next.js API Routes 傳送至 Supabase，存入 posts 表。
### 5.3 評論與互動流程
1. 用戶瀏覽符合 allowed_viewers 條件的文章。
2. 用戶若滿足 allowed_commenters 條件，則可在文章下留言，資料存入 comments 表。
3. 用戶對文章或評論點讚，更新 likes 表與相應的 likes_count。
4. 利用 Supabase Realtime 或 WebSocket 實現即時更新通知。
### 5.4 獎勵發放流程 (CELO 整合)
#### 自動獎勵觸發
* 當用戶在啟用獎勵的文章下發表評論時，系統檢查該用戶是否符合獎勵條件：
- Type 1: 檢查是否為第一個評論者
- Type 2: 檢查該用戶是否已經獲得過此文章的獎勵
* 符合條件時，在rewards表中創建記錄，設置status為'pending'
#### 獎勵領取流程
* 用戶可在個人頁面查看可獲得的獎勵列表
* 用戶點擊領取按鈕，前端呼叫智能合約進行鏈上獎勵發放
* 發放成功後，將rewards表中對應記錄的status更新為'claimed'
Sign in with Wallet
Connect another wallet