GS DeFi DApp 技术设计文档（TDD）

📋1. 文档说明 & PRD 链接

本 TDD 描述 GS DeFi DApp 的技术实现方案，聚焦「怎么做」。 业务需求、规则、验收标准统一在 PRD 中维护。本文档各章节通过需求 ID 回引 PRD， 实现时请同时打开两份文档对照。

需求 ID 引用约定

• FR-x.y：功能需求（Functional Requirement），如 FR-1.1 开新仓
• BR-x：业务规则（Business Rule），如 BR-1 质押率 70%
• NFR-x：非功能需求（Non-Functional Requirement），如 NFR-2 国际化
• 本文档章节标题旁的需求标签 → 表示该章节是对应需求的技术实现

⚙️2. 技术栈

📁3. 项目结构

DApp 作为独立子目录放在现有合约项目根目录下：

gs-defi-protocol/
├── contracts/               # 现有合约（不修改）
├── test/                    # 现有测试（不修改）
├── docs/                    # 合约需求文档
└── dapp/                    # ← 新建 DApp 目录
    ├── app/
    │   ├── layout.tsx           # 根布局（Providers 注入）
    │   ├── page.tsx             # 首页 / 仪表盘
    │   ├── lending/
    │   │   └── page.tsx         # 质押借贷页
    │   ├── swap/
    │   │   └── page.tsx         # Swap 兑换页
    │   ├── faucet/
    │   │   └── page.tsx         # 水龙头页
    │   └── api/
    │       └── faucet/
    │           └── route.ts     # 服务端转账 API（持私钥）
    ├── components/
    │   ├── layout/
    │   │   ├── Navbar.tsx
    │   │   ├── Footer.tsx
    │   │   └── LanguageSwitcher.tsx
    │   ├── lending/
    │   │   ├── BorrowForm.tsx       # 开仓表单
    │   │   ├── OrderList.tsx        # 我的订单
    │   │   ├── RepayModal.tsx       # 还款弹窗
    │   │   └── LiquidatePanel.tsx   # 清算面板
    │   ├── swap/
    │   │   ├── SwapCard.tsx
    │   │   └── SlippageSettings.tsx
    │   └── faucet/
    │       └── FaucetCard.tsx
    ├── hooks/
    │   ├── usePledgeLending.ts  # openOrder / repay / liquidate
    │   ├── useSwap.ts           # swap / getAmountsOut
    │   └── useTokenBalance.ts   # GS/GB/GC 余额 + approve
    ├── config/
    │   ├── chains.ts            # gsc_v2_test 网络定义
    │   ├── contracts.ts         # 合约地址常量
    │   └── abis/                # ABI JSON 文件（从 artifacts/ 导出）
    │       ├── PledgeLending.json
    │       ├── TriggerParams.json
    │       ├── UniswapV2Router02.json
    │       └── ERC20.json
    ├── lib/
    │   ├── i18n/
    │   │   ├── zh.json          # 中文翻译
    │   │   └── en.json          # 英文翻译
    │   └── faucet-cooldown.ts   # 服务端冷却时间 Map
    ├── public/
    │   └── logo.svg
    ├── .env.local               # 私钥等敏感配置（不提交 git）
    ├── .env.example             # 环境变量示例模板（提交 git，含所有变量占位符）
    ├── package.json
    ├── tailwind.config.ts
    └── tsconfig.json

🔗4. 合约对接

网络配置（动态加载）

网络参数全部从环境变量读取，部署到不同环境（测试网 / 主网）时只需修改 .env， 无需重新编译代码。所有配置项使用 NEXT_PUBLIC_ 前缀以便客户端可读。

// config/chains.ts
export const appChain = {
  id: Number(process.env.NEXT_PUBLIC_CHAIN_ID),
  name: process.env.NEXT_PUBLIC_CHAIN_NAME!,
  nativeCurrency: {
    name:     process.env.NEXT_PUBLIC_NATIVE_NAME!,
    symbol:   process.env.NEXT_PUBLIC_NATIVE_SYMBOL!,
    decimals: Number(process.env.NEXT_PUBLIC_NATIVE_DECIMALS ?? 18),
  },
  rpcUrls: {
    default: { http: [process.env.NEXT_PUBLIC_RPC_URL!] },
  },
  blockExplorers: {
    default: {
      name: process.env.NEXT_PUBLIC_EXPLORER_NAME!,
      url:  process.env.NEXT_PUBLIC_EXPLORER_URL!,
    },
  },
}

合约地址（待部署后填入）

核心合约交互一览

合约关键枚举（前端需对齐）

// 借出类型
enum LoanType { GB, GC }            // GB=0, GC=1

// 订单状态（合约存储层）
enum OrderStatus { Active, Repaid, Liquidated }

// 还款状态（getRepayStatus 返回，前端展示用）
enum RepayStatus {
  NotDue,       // 未到期（block.timestamp < repayDueDate）
  Repayable,    // 可还款（repayDueDate ≤ now ≤ repayDeadline）
  Overdue,      // 已逾期（now > repayDeadline，可被清算）
  Repaid,       // 已结清
  Liquidated    // 已清算
}

关键业务规则提醒

合约 ABI 文件来源

从已编译的 artifacts/contracts/ 直接导出 ABI 到 dapp/config/abis/:

artifacts/contracts/PledgeLending.sol/PledgeLending.json       → PledgeLending.json
artifacts/contracts/TriggerParams.sol/TriggerParams.json       → TriggerParams.json
artifacts/contracts/interfaces/IPledgeLending.sol/...          → IPledgeLending.json
artifacts/contracts/interfaces/ITriggerParams.sol/...          → ITriggerParams.json
artifacts/contracts/uniswap-v2-periphery/.../Router02.json     → UniswapV2Router02.json
artifacts/.../ERC20.json                                       → ERC20.json

🖥️5. 页面设计

5.0 设计语言 & 整体布局

参考 Sky Protocol（MakerDAO 新版）的 DApp 设计语言，采用 左侧固定边栏 + 右侧主内容区的现代布局。首页作为"中央枢纽"， 所有复杂操作下沉到子页面，卡片化按功能分组呈现。

整体结构示意

┌──────────────────────────────────────────────────────────────┐
│  ⬡ GS DeFi                    [🌐 GSC V2 ▼]  [Connect Wallet]│  ← 顶栏
├────────────┬─────────────────────────────────────────────────┤
│ 📊 Dashboard│                                                 │
│ 💰 Lending  │     主内容区（按功能分组的卡片网格）           │
│ 🔄 Swap     │                                                 │
│ 🚰 Faucet   │                                                 │
│            │                                                 │
│ ┌────────┐ │                                                 │
│ │Balances│ │                                                 │
│ │ 我的资产│ │                                                 │
│ │  GS:.. │ │                                                 │
│ │  GB:.. │ │                                                 │
│ │  GC:.. │ │                                                 │
│ └────────┘ │                                                 │
│            │                                                 │
│ 🌐 中/EN   │                                                 │
└────────────┴─────────────────────────────────────────────────┘

5.1 首页 / 仪表盘 / （实现 FR-4 + FR-4.2）

用户进入后的"中央枢纽"——左侧持久 Balances 卡片显示用户资产， 右侧按功能语义分组（质押借贷 / 兑换交易 / 新手入口 / 协议数据）。 每个分组下面是 1-2 行入口卡片，点击进入子页面执行实际操作。

左侧边栏（Sidebar）

• 顶部导航菜单（垂直）：Dashboard / Lending / Swap / Faucet，图标 + 文字 + 当前页高亮
• 中部 Balances 持久卡片：常驻显示 GS / GB / GC 余额（未连接钱包时显示插画 + Connect Wallet 引导）
• 底部：语言切换（🇨🇳 中文 / 🇺🇸 EN）、版本号、外部链接（GitHub / Docs / Block Explorer）

右侧主内容区（分组卡片）

• 欢迎区：协议标题 + 一句话介绍 + 网络状态指示灯（🟢 正常 / 🟡 延迟 / 🔴 错误）
• 质押 & 借贷分组：「开新仓」「我的订单」两张入口卡片 → 跳转 /lending
• 兑换交易分组：「GS ⇄ GC」「GB ⇄ GC」实时汇率卡片 → 跳转 /swap?pair=...
• 新手入口分组：「领取测试币」单卡片（仅新地址显示）→ 跳转 /faucet
• 协议数据分组：TVL、总借出量、当前利率等只读统计

5.2 质押借贷页 /lending （实现 FR-1.1 ~ FR-1.5，约束 BR-1 ~ BR-4、BR-7、BR-10）

参考 MakerDAO / Aave 风格，左侧操作面板，右侧订单列表。具体业务规则见 PRD BR-1（质押率 70%）、BR-3（周期）、BR-7（利率来源）。

开新仓（Borrow）流程

• 借出类型切换:GB Tab（显示"无利息"）/ GC Tab（显示实时利率，来源 TriggerParams.getGCDailyRate()）
• 质押周期按钮组:从 getGBPledgeParams() / getGCPledgeParams() 动态读取（默认 360 / 720 / 1080，admin 可动态增减）
• 切换 LoanType 时重新拉取对应参数(GB 和 GC 的周期 → 质押率映射是独立的)
• GS 数量输入框 + MAX 按钮,实时计算可借出量:
  · GB:gsAmount × pledgeRate × getGSGB()
  · GC:gsAmount × pledgeRate × getGSGC5()
• 信息汇总:质押率、借出量、到期日（repayDueDate）、宽限期截止（repayDeadline）、预计满周期利息（GC）
• 两步操作:先 ERC20.approve(PledgeLending, gsAmount)（检查 allowance 够则跳过），再 openPosition()
• 开仓成功后,从 PositionOpened 事件中拿到 orderId 跳转到「我的订单」

我的订单列表

• 数据源:getUserOrders(address) → bytes32[] → 逐个 getOrder(orderId) 拿 OrderView（含担保率、利息、应还、还款状态）
• 状态映射 RepayStatus 枚举（合约返回）+ 前端衍生:
  • NotDue 且距到期 ≥ 30 天 → 正常
  • NotDue 且距到期 < 30 天 → 临近到期
  • Repayable → 可还款
  • Overdue 或 担保率 < 100% → 可清算
• 「还款」按钮:仅 Repayable 状态可点击；点击弹窗显示 estimatedRepay，需 approve(GB/GC, estimatedRepay) 后调 repay(orderId)
• 「补仓」按钮:全状态可见;弹窗输入追加 GS,显示补仓后新担保率（前端模拟计算）,需 approve(GS, addAmount) 后调 addCollateral(orderId, gsAmount)
• 可清算订单单独面板:筛选 Overdue 或担保率 < 100% 的订单,显示可得 1% GS 奖励,一键调 liquidate(orderId)
• 已结清 / 已清算订单默认折叠,可切换"历史"标签查看

5.3 Swap 兑换页 /swap （实现 FR-2.1、FR-2.2，约束 BR-8、BR-9）

参考 Uniswap V2 经典界面，居中卡片布局。默认滑点 BR-8，手续费 BR-9。

• 支持交易对：GS ⇄ GC、GB ⇄ GC（下拉选择代币）
• From 输入框输入数量 → 实时调用 getAmountsOut 计算 To 数量
• 中间「↕」按钮反转兑换方向
• 汇率显示：1 GS = x.xx GC，可点击翻转
• 滑点设置：0.1% / 0.5% / 1.0% / 自定义（默认 0.5%）
• 交易详情折叠面板：最小获得量、价格影响（>3% 显示警告）、路由路径、手续费（0.3%）
• 「兑换」按钮：先检查授权，不足则显示「授权」按钮；授权后显示「确认兑换」
• 交易成功：Toast 通知 + TX Hash 链接（区块链浏览器）

5.4 水龙头页 /faucet （实现 FR-3.1、FR-3.2，约束 BR-5、BR-6）

简洁卡片，降低新用户上手门槛。冷却时间 BR-5，领取量 BR-6。

• 页面顶部说明文案：「测试网专用，每个地址每 24 小时可领取一次」
• 三代币展示卡：GS / GB / GC，每种显示「每次领取量」和「当前余额」
• 一键领取按钮 → 请求 POST /api/faucet → 服务端转账
• 冷却状态：倒计时显示距下次可领时间（HH:MM:SS）
• 领取成功：3 笔转账的 TX Hash 均展示，可点击跳转区块链浏览器
• 失败提示：余额不足（水龙头钱包余额不足提示管理员充值）/ 网络错误

🧭6. 导航栏 & 钱包连接 （实现 FR-5.1、FR-5.2）

参考 Sky Protocol 的双层导航模式：顶栏极简（只放 Logo + 网络 + Connect Wallet）， 左侧边栏承载主导航（垂直图标+文字），并嵌入持久 Balances 卡片。

顶栏（Top Bar，全宽固定）

• Logo（左）：「⬡ GS DeFi」+ 副标题「Genesis Chain」
• 网络切换（右）：显示当前网络名 + 绿色指示灯，点击可切换
• 连接钱包按钮（右）：使用 RainbowKit <ConnectButton />
• 已连接状态：按钮变为「地址缩写 + GS 余额」胶囊，点击展开下拉菜单（断开连接 / 复制地址 / 区块链浏览器）
• 错误网络提示：连接到非 ChainID 44 时，显示红色横幅「请切换到 GSC V2 测试网」+ 一键切换按钮

左侧边栏（Sidebar，桌面端固定 240px）

• 主导航菜单（垂直）：📊 Dashboard / 💰 Lending / 🔄 Swap / 🚰 Faucet，当前页用紫色高亮 + 左侧条形指示
• Balances 持久卡片（位于导航下方）：常驻显示 GS / GB / GC 余额，未连接钱包时显示插画 + Connect Wallet 引导
• 底部工具区：🌐 语言切换（🇨🇳 中文 ↔ 🇺🇸 English，保存到 localStorage） · 📖 文档链接 · 🐙 GitHub · 🔍 GSCScan

移动端（< 768px）

• 顶栏保留 Logo + Connect Wallet 按钮（精简）
• 左侧边栏 收起为底部 Tab Bar：四个图标（Dashboard / Lending / Swap / Faucet）固定底部
• Balances 卡片下沉到 Dashboard 主区顶部
• 语言切换移入"更多"汉堡菜单

🌐7. 国际化实现 （实现 NFR-2）

使用 next-intl 实现双语切换，翻译文件存于 lib/i18n/。需求详情见 PRD NFR-2。

// lib/i18n/zh.json（示例）
{
  "nav": {
    "home": "首页",
    "lending": "质押借贷",
    "swap": "Swap 兑换",
    "faucet": "水龙头"
  },
  "lending": {
    "borrow": "开仓借款",
    "repay": "还款",
    "liquidate": "清算",
    "pledgeRate": "质押率"
  }
}

• 默认语言：中文（zh），浏览器语言自动检测
• 语言选择持久化到 localStorage，刷新后保留
• URL 路径前缀：/zh/lending、/en/lending
• 数字格式化随语言变化（如千分位分隔符）

🔧8. 水龙头 API 设计 （实现 FR-3.1、FR-3.2，约束 BR-5、BR-6、NFR-4）

接口

POST /api/faucet
Content-Type: application/json

// Request
{ "address": "0x1234...abcd" }

// Response 200
{
  "success": true,
  "txHashes": {
    "GS": "0xabc...",
    "GB": "0xdef...",
    "GC": "0x789..."
  },
  "nextClaimAt": "2026-05-16T10:30:00Z"
}

// Response 429 (冷却中)
{ "success": false, "error": "COOLDOWN", "nextClaimAt": "..." }

// Response 400 (地址无效)
{ "success": false, "error": "INVALID_ADDRESS" }

服务端逻辑

📱9. 移动端实现 （实现 NFR-3）

🔑10. 环境变量 （约束 NFR-4）

环境变量列表

# dapp/.env.local（不提交 git，本地实际配置）
# dapp/.env.example（提交 git，作为模板供他人参考）

# ── 水龙头钱包（服务端专用，无 NEXT_PUBLIC_ 前缀）
FAUCET_PRIVATE_KEY=0x...              # 水龙头钱包私钥

# ── 每次领取量
FAUCET_GS_AMOUNT=1000                 # 单位：GS（整数）
FAUCET_GB_AMOUNT=500
FAUCET_GC_AMOUNT=500

# ── 网络参数（动态加载，部署不同链时修改这里即可）
NEXT_PUBLIC_CHAIN_ID=44
NEXT_PUBLIC_CHAIN_NAME=Genesis Chain V2 Testnet
NEXT_PUBLIC_NATIVE_NAME=GS
NEXT_PUBLIC_NATIVE_SYMBOL=GS
NEXT_PUBLIC_NATIVE_DECIMALS=18
NEXT_PUBLIC_RPC_URL=https://v2test.genesischain.io
NEXT_PUBLIC_EXPLORER_NAME=GSCScan
NEXT_PUBLIC_EXPLORER_URL=https://v2scan.genesischain.io

# ── 合约地址（部署后填入）
NEXT_PUBLIC_GS_TOKEN=0x...
NEXT_PUBLIC_GB_TOKEN=0x...
NEXT_PUBLIC_GC_TOKEN=0x...
NEXT_PUBLIC_PLEDGE_LENDING=0x...
NEXT_PUBLIC_ROUTER=0x...
NEXT_PUBLIC_FACTORY=0x...
NEXT_PUBLIC_TRIGGER_PARAMS=0x...

.env.example 示例文件（提交 git）

为方便团队协作与新环境部署，在仓库中提供一份 .env.example 模板。 该文件 仅包含变量名和占位符，不含任何真实私钥或敏感地址，可安全提交到 git。 新成员克隆项目后 cp .env.example .env.local 再填充实际值即可。

# dapp/.env.example（提交到 git，作为团队配置模板）

# ── 水龙头钱包（服务端专用）
FAUCET_PRIVATE_KEY=                   # 留空，本地填入实际私钥

# ── 每次领取量
FAUCET_GS_AMOUNT=1000
FAUCET_GB_AMOUNT=500
FAUCET_GC_AMOUNT=500

# ── 网络参数（按部署目标链修改）
NEXT_PUBLIC_CHAIN_ID=44
NEXT_PUBLIC_CHAIN_NAME=Genesis Chain V2 Testnet
NEXT_PUBLIC_NATIVE_NAME=GS
NEXT_PUBLIC_NATIVE_SYMBOL=GS
NEXT_PUBLIC_NATIVE_DECIMALS=18
NEXT_PUBLIC_RPC_URL=https://v2test.genesischain.io
NEXT_PUBLIC_EXPLORER_NAME=GSCScan
NEXT_PUBLIC_EXPLORER_URL=https://v2scan.genesischain.io

# ── 合约地址（部署后填入）
NEXT_PUBLIC_GS_TOKEN=
NEXT_PUBLIC_GB_TOKEN=
NEXT_PUBLIC_GC_TOKEN=
NEXT_PUBLIC_PLEDGE_LENDING=
NEXT_PUBLIC_ROUTER=
NEXT_PUBLIC_FACTORY=
NEXT_PUBLIC_TRIGGER_PARAMS=

🗺️11. 开发阶段计划