DApp Studio

Architect the Decentralized Future

一個基於 Truffle + Express + React 架構的 Web3 應用程式開發平台，專注於 ERC20 代幣交易監控和智能合約互動。

🎯 項目概覽

DApp Studio 提供完整的 Web3 開發解決方案，包含智能合約部署、API 服務、前端界面和實時交易監控儀表板。

核心功能

🔗 智能合約管理 - Truffle 框架部署和測試
🖥️ 交易監控儀表板 - 實時多合約事件監控
🌐 Web3 前端 - React + Drizzle 用戶界面
🔧 API 服務 - Express 後端和認證系統
🧪 完整測試 - 單元測試 + E2E 測試

📁 項目結構

DApp Studio/
├── 🎯 dashboard/              # 主要交易監控儀表板 (v0.2.0)
│   ├── src/                   # TypeScript 源代碼
│   ├── dist/                  # 構建輸出
│   └── *.md                   # 項目文檔
├── 🌐 frontend/               # 原始 Web3 前端
│   ├── src/                   # React + Drizzle 源代碼
│   └── public/                # 靜態資源
├── 🔧 backend/                # Express API 服務
│   ├── src/                   # Node.js 源代碼
│   └── test/                  # API 測試
├── 📜 contracts/              # Truffle 智能合約
│   ├── contracts/             # Solidity 合約
│   ├── migrations/            # 部署腳本
│   └── test/                  # 合約測試
├── 🧪 e2e/                    # Playwright E2E 測試
├── 📚 docs/                   # 分類文檔
│   ├── architecture/          # 架構設計文檔
│   ├── dashboard/             # 儀表板相關文檔
│   └── testing/               # 測試指南
└── 🛠️ scripts/               # 部署和工具腳本

🚀 快速開始

環境要求

Node.js 22+
npm 或 yarn
Ganache (本地區塊鏈)
MetaMask 瀏覽器擴展

1. 安裝依賴

# 安裝根目錄依賴
npm install

# 安裝各子項目依賴
npm run install:all

2. 啟動本地區塊鏈

# 啟動 Ganache
ganache --host 127.0.0.1 --port 8545

3. 配置 MetaMask

添加本地網絡

打開 MetaMask 擴展
點擊網絡選擇器 → "添加網絡" → "手動添加網絡"
填入以下配置：
- 網絡名稱: Ganache Local
- RPC URL: http://127.0.0.1:8545
- 鏈 ID: 1337
- 貨幣符號: ETH
點擊"保存"

導入測試帳戶

複製 Ganache 輸出的私鑰 (Private Keys)
MetaMask → 帳戶圖標 → "導入帳戶"
貼上私鑰並點擊"導入"
確認帳戶餘額顯示 ~100 ETH

💡 提示: 重啟 Ganache 後需要在 MetaMask 設定中"清除活動標籤數據"以重置 nonce

詳細設定請參考：MetaMask 設定指南

4. 部署智能合約

# 部署到本地網絡
npm run deploy

5. 啟動服務

選項 A: 交易監控儀表板 (推薦)

cd dashboard
npm run dev
# 訪問 http://localhost:5174

選項 B: 完整 DApp 服務

# 分別啟動服務
npm run dev:backend    # API: http://localhost:3001
npm run dev:frontend   # 前端: http://localhost:5173

📊 主要項目

🎯 Dashboard (v0.2.0) - 推薦使用

獨立交易監控儀表板

✅ 多合約實時監控
✅ 漸進式揭露 UX 設計
✅ 實時分析和圖表
✅ 數據導出 (JSON/CSV)
✅ 智能通知系統
✅ 確認對話框系統 (戰略性摩擦)
✅ 情境提示系統 (首次用戶引導)

cd dashboard
npm run dev        # 開發模式
npm run build      # 生產構建
npm run preview    # 預覽構建

🌐 Frontend - 原始 DApp

完整 Web3 應用前端

React + Drizzle 架構
MetaMask 集成
智能合約互動
用戶認證系統

cd frontend
npm run dev        # 開發模式
npm test          # 運行測試

🔧 Backend - API 服務

Express REST API

JWT 認證
區塊鏈數據 API
用戶管理
交易歷史

cd backend
npm run dev        # 開發模式
npm test          # 運行測試

🧪 測試

單元測試

# 智能合約測試
cd contracts && npm test

# 前端測試  
cd frontend && npm test

# 後端測試
cd backend && npm test

E2E 測試

cd e2e
npm run test              # 運行所有測試
npm run test:headed       # 有界面模式
npm run test:auth         # 僅認證測試

📚 文檔

架構文檔 (`docs/architecture/`)

儀表板文檔 (`docs/dashboard/`)

測試文檔 (`docs/testing/`)

🛠️ 開發工具

腳本命令

npm run dev           # 啟動完整開發環境
npm run build         # 構建所有項目
npm run test          # 運行所有測試
npm run deploy        # 部署智能合約
npm run clean         # 清理構建文件

工具鏈

智能合約: Truffle + Solidity
前端: React + TypeScript + Vite
後端: Express + Node.js
測試: Mocha + Vitest + Playwright
區塊鏈: Ganache + Web3.js

🚨 故障排除

MetaMask 問題

Nonce 錯誤 (交易卡住)

# 症狀：交易失敗或無限等待
# 原因：重啟 Ganache 後 nonce 不同步
# 解決：MetaMask → 設定 → 進階 → "清除活動標籤數據"

連接失敗

# 檢查網絡配置
RPC URL: http://127.0.0.1:8545
Chain ID: 1337
# 確認 Ganache 正在運行
ganache --host 127.0.0.1 --port 8545

餘額不更新

確認已切換到 "Ganache Local" 網絡
確認使用正確的導入帳戶
重新整理頁面或重啟 MetaMask

部署問題

合約部署失敗

# 檢查 Ganache 狀態
ps aux | grep ganache

# 重新部署
npm run deploy

# 檢查部署結果
npm run verify

ABI 不匹配錯誤

# 重新編譯和導出 ABI
cd contracts && npx truffle compile
npm run export:abi

端口衝突

# 檢查端口使用情況
lsof -i :8545  # Ganache
lsof -i :3001  # Backend
lsof -i :5173  # Frontend
lsof -i :5174  # Dashboard

開發環境問題

Node.js 版本不兼容

# 檢查版本
node --version  # 需要 22+

# 使用 nvm 切換版本
nvm use 22

依賴安裝失敗

# 清理緩存
npm cache clean --force
rm -rf node_modules package-lock.json

# 重新安裝
npm install

📖 進階指南

🚀 部署相關

部署指南 - 部署到不同網絡
Ganache 升級指南 - 本地環境設定
部署實施總結 - 部署最佳實踐

🛠️ 開發相關

智能合約開發 - ERC-20 合約開發
工具鏈現代化 - 開發環境配置
事件驅動架構 - 架構設計
項目憲法 - 開發規範

🧪 測試相關

測試手冊 - 手動測試指南
E2E 測試指南 - 自動化測試
E2E 實施總結 - 測試架構

🎨 設計相關

設計原則 - UX 設計原則
品牌設計系統 - 視覺設計規範
UX 優化總結 - 用戶體驗優化

📊 儀表板相關

儀表板 README - 獨立儀表板文檔
UI 修復總結 - 界面修復記錄
UX 優化待辦 - 未來改進計劃

❓ 常見問題 (FAQ)

Q: 為什麼推薦使用 Dashboard 而不是 Frontend？ A: Dashboard (v0.2.0) 是獨立的交易監控工具，具有更現代的 UX 設計、實時分析和完整的監控功能。Frontend 是原始的 Web3 DApp，主要用於學習和開發參考。

Q: 如何在不同網絡間切換？ A: 修改 truffle-config.js 中的網絡配置，然後使用 NETWORK=<network_name> npm run deploy 部署到指定網絡。

Q: 如何添加新的智能合約？ A: 1) 在 contracts/contracts/ 中創建 .sol 文件，2) 在 contracts/migrations/ 中添加部署腳本，3) 運行 npm run deploy。

Q: 如何自定義儀表板？ A: 參考 dashboard/src/ 中的組件，按照設計原則文檔進行修改。支持多合約監控和自定義通知。

Q: 測試失敗怎麼辦？ A: 1) 確認所有服務正在運行，2) 檢查 MetaMask 配置，3) 查看 docs/testing/ 中的測試指南，4) 運行 npm run test 查看詳細錯誤。

🎨 設計原則

基於設計原則文檔：

別讓使用者思考 - 直覺化操作
明確選擇 - 清晰的操作路徑
無情簡化 - 漸進式功能揭露

🔄 開發狀態

✅ 已完成

智能合約部署和測試
Express API 和認證系統
React 前端和 Web3 集成
獨立交易監控儀表板 (v0.2.0)
UX 優化和設計原則應用
確認對話框系統 (戰略性摩擦)
情境提示系統 (首次用戶體驗)
E2E 測試框架
項目結構整理

🔄 進行中

性能優化和虛擬滾動
高級分析功能擴展
移動端適配優化

📋 計劃中

多鏈支持
用戶測試和反饋收集
部署自動化

🤝 貢獻

Fork 項目
創建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
開啟 Pull Request

📄 許可證

本項目採用 MIT 許可證 - 查看 LICENSE 文件了解詳情。

🔗 相關鏈接

DApp Studio - Architect the Decentralized Future 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 49 Commits
.specify		.specify
backend		backend
contracts		contracts
dashboard		dashboard
docs		docs
e2e		e2e
frontend		frontend
migrations		migrations
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
check-metamask.html		check-metamask.html
package-lock.json		package-lock.json
package.json		package.json
progress.bak		progress.bak
progress.md		progress.md
test-contract-call.js		test-contract-call.js

License

iim0663418/Dapp_studio

Folders and files

Latest commit

History

Repository files navigation