# GBC

**Repository Path**: charyHe/gbc

## Basic Information

- **Project Name**: GBC
- **Description**: 123
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-03
- **Last Updated**: 2025-12-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GBC DApp

一个使用现代技术栈构建的最佳实践 DApp 项目。

## 技术栈

- **React 18** - UI 框架
- **TypeScript** - 类型安全
- **Vite** - 构建工具
- **Tailwind CSS** - 实用优先的 CSS 框架
- **Material-UI (MUI)** - React UI 组件库
- **Reown AppKit** - 钱包连接解决方案（原 WalletConnect）
- **Wagmi** - React Hooks for Ethereum
- **Viem** - 类型安全的以太坊库
- **TanStack Query** - 数据获取和状态管理
- **Zustand** - 轻量级状态管理

## 快速开始

### 安装依赖

```bash
npm install
```

### 开发

```bash
npm run dev
```

应用将在 `http://localhost:3000` 启动

### 构建

```bash
npm run build
```

### 预览生产构建

```bash
npm run preview
```

## 项目结构

```
src/
├── lib/             # 核心库层
│   └── web3/        # Web3 集成层（配置、适配器、AppKit）
├── store/           # 状态管理层
│   └── web3Store.ts # Web3 全局状态（Zustand）
├── hooks/           # React Hooks 层
│   └── web3/        # Web3 相关 Hooks（AppKit、余额、钱包）
├── providers/       # Provider 组件层
│   └── Web3Provider.tsx # Web3 Provider
├── components/      # UI 组件层
│   └── Layout.tsx   # 布局组件
├── pages/           # 页面组件层
│   └── HomePage.tsx # 首页
├── utils/           # 工具函数层
│   ├── format.ts    # 格式化工具
│   └── constants.ts # 常量定义
├── App.tsx          # 根组件
├── main.tsx         # 入口文件
└── index.css        # 全局样式
```

详细架构说明请查看 [ARCHITECTURE.md](./ARCHITECTURE.md)

## 配置说明

### Reown AppKit Project ID

项目已配置 Reown AppKit，Project ID 为：`9a7b7145a32ccf527873290d3fd5c047`

如需修改，请编辑 `src/lib/web3/config.ts` 文件。

### 支持的网络

- Ethereum Mainnet
- Sepolia Testnet
- Polygon
- Arbitrum
- Optimism

## 功能特性

- ✅ 钱包连接（支持多种钱包）
- ✅ 账户信息显示
- ✅ 余额查询
- ✅ 网络切换
- ✅ 响应式设计
- ✅ TypeScript 类型安全
- ✅ 现代化 UI/UX
- ✅ 分层架构设计
- ✅ 单一职责原则
- ✅ Zustand + React Query 状态管理

## 架构特点

### 1. Web3 集成层
- **单一职责：** 每个模块只负责一个功能
- **配置分离：** 配置、适配器、AppKit 分别管理
- **易于测试：** 纯函数和配置，无副作用

### 2. 状态管理
- **Zustand：** 管理 UI 状态（连接状态、账户信息）
- **React Query：** 管理服务器状态（余额、交易等）
- **自动同步：** Hooks 自动同步 Wagmi 状态到 Zustand

### 3. React Hooks 集成
- **useAppKit：** AppKit 连接状态和账户信息
- **useAccountBalance：** 余额查询逻辑
- **useWallet：** 钱包综合功能（组合其他 Hooks）

## 开发指南

### 使用 Web3 Hooks

```tsx
import { useWallet } from '@/hooks/web3'

function MyComponent() {
  const {
    address,
    isConnected,
    chainId,
    formattedBalance,
  } = useWallet()
  
  // ...
}
```

### 使用 Zustand Store

```tsx
import { useWeb3Store } from '@/store/web3Store'

function MyComponent() {
  const { address, isConnected, chainId } = useWeb3Store()
  
  // ...
}
```

### 使用 Web3 集成层

```tsx
import { wagmiAdapter, queryClient, appKit } from '@/lib/web3'
import { PROJECT_ID, SUPPORTED_NETWORKS } from '@/lib/web3'
```

### 添加新的 Web3 Hook

1. 在 `src/hooks/web3/` 中创建新 Hook
2. 遵循单一职责原则
3. 在 `index.ts` 中导出
4. 如需要，同步状态到 Zustand Store

详细架构说明请查看 [ARCHITECTURE.md](./ARCHITECTURE.md)

## 许可证

MIT