📘 阅读指南：本文档是 GS DeFi DApp 的 产品需求文档（PRD）， 定义 「做什么、为什么、约束是什么」。技术实现细节请参考配套的 技术设计文档（TDD）， TDD 通过需求 ID（FR-x / BR-x / NFR-x）回引本文档。

目录

  1. 背景与目标
  2. 用户角色
  3. 业务概念 & 术语表
  4. 功能需求（FR）
    1. FR-1 质押借贷
    2. FR-2 Swap 兑换
    3. FR-3 水龙头
    4. FR-4 仪表盘数据展示
    5. FR-5 钱包连接与会话
  5. 业务规则（BR）
  6. 非功能需求（NFR）
  7. 验收标准（AC）
  8. 范围之外

📋1. 背景与目标

1.1 背景

Genesis Chain 已部署一套 DeFi 协议合约（PledgeLending 质押借贷、UniswapV2 兑换、TriggerParams 利率源） 到 gsc_v2_test 测试网（ChainID 44）。当前缺乏面向终端用户的 Web 前端， 用户只能通过原始 RPC 调用合约，使用门槛极高。

1.2 目标

1.3 非目标（v1.0 不做）

👥2. 用户角色

🆕 新手用户

首次接触 GS 协议，没有 GS/GB/GC 代币。 主要诉求：领取测试币、了解协议机制。 高频路径：Faucet → Dashboard 浏览

💼 借贷用户

持有 GS，希望通过质押借出稳定币 GB 或 GC 获取流动性。 关注：质押率、利率、到期日、清算风险。 高频路径：Lending 开仓 → 监控订单 → 还款

🔄 交易用户

在 GS / GB / GC 之间兑换以平衡资产或套利。 关注：实时汇率、滑点、价格影响。 高频路径：Swap 兑换

🛡️ 清算者

监控全局订单，发现可清算订单后触发清算获取 1% GS 奖励。 关注：清算线、奖励金额。 高频路径：Lending 清算面板

📖3. 业务概念 & 术语表

GS（Genesis Share）
Genesis Chain 原生代币，承载治理权 + 收益权。本 DApp 中作为协议质押物。
GB（Genesis Bond）
公链的债券代币。由用户质押 GS 借出，无利息到期归还本金即可。
GC（Genesis Cash）
公链的支付代币 / 通货。由用户质押 GS 借出，有利率，到期归还本金 + 利息。
质押率 / Pledge Rate
借出量 ÷ 质押 GS 价值 的最大比例（v1.0 固定 70%）。
清算线 / Liquidation Threshold
当订单担保率（质押价值 ÷ 借出价值）跌破清算线时，任何人均可触发清算。
质押周期 / Cycle
订单的固定锁定期。v1.0 提供 360 / 720 / 1080 天三档。
补仓 / Add Collateral
在订单存续期内追加 GS 质押，提高担保率以避免清算。
水龙头 / Faucet
测试网专用，向新地址免费发放小额 GS / GB / GC，便于上手体验。
滑点 / Slippage
Swap 时实际成交价与报价的最大允许偏差（默认 0.5%）。

⚙️4. 功能需求（Functional Requirements）

FR-1 质押借贷

FR-1.1开新仓（Borrow）
用户选择借出类型（GB 或 GC）+ 质押周期 + GS 数量，授权后调用合约 PledgeLending.openPosition(gsAmount, cycleDays, loanType) 开仓。
  • 开仓前必须先 ERC20.approve 质押的 GS
  • 系统按 BR-1 质押率实时计算可借出量
  • loanType 枚举：GB = 0 / GC = 1
  • GC 订单需展示当前利率（来源见 BR-7）
  • 开仓成功后跳转到「我的订单」展示新仓位
FR-1.2补仓（Add Collateral）
在订单存续期内，用户可追加 GS 质押，提高担保率以避免清算。
  • 仅订单所有者可操作
  • 补仓前需授权追加的 GS 数量
  • 展示补仓前后的担保率对比
FR-1.3还款（Repay）
在还款窗口期内归还借出代币 + 利息（GC），赎回质押的 GS。调用 PledgeLending.repay(orderId)。
  • 还款窗口（BR-11）：到期日（repayDueDate） ≤ 当前时间 ≤ 宽限期截止日（repayDeadline）
  • 不允许提前还款——未到期调用 repay 会被合约 revert（"not due yet"），UI 需在订单状态为 NotDue 时禁用还款按钮
  • 超过宽限期变为 Overdue，无法再还款，会被任何人清算（FR-1.4）
  • GB 订单：还本金 debtAmount（合约通过 burnFrom 销毁）
  • GC 订单：还本金 + 实时利息（合约通过 burnFrom 销毁）
  • 应还数量从 getEstimatedRepayment(orderId) 实时读取
  • 还款前需 ERC20.approve 对应数量的 GB 或 GC 给 PledgeLending 合约
  • 还款成功后订单 status 变更为 Repaid，全部 GS 释放回借款人
FR-1.4清算（Liquidate）
任何地址可调用 PledgeLending.liquidate(orderId) 触发清算。
  • 触发条件（满足任一即可）：
    • ① 资不抵债:担保率 collateralRate < 100%（即 1e18）
    • ② 逾期:当前时间 > repayDeadline
  • 清算分配:质押 GS 的 1% 转给清算人（BR-4），99% 销毁（burnFrom）
  • UI 应有专门「可清算订单」面板，调用 getCollateralRate + getRepayStatus 筛选符合条件的订单
  • 清算成功后订单 status 变更为 Liquidated，记录 liquidator 地址与 liquidatedTime
FR-1.5订单查询
  • 「我的订单」:调用 getUserOrders(address) 取得用户全部订单 ID 数组（bytes32[]），逐个调用 getOrder(orderId) 获取 OrderView 详情
  • OrderView 一次返回:订单原始数据 + collateralRate 担保率 + accruedInterest 实时利息 + estimatedRepay 应还数量 + repayStatus 还款状态
  • 每条订单展示:订单 ID（截断）、类型、质押 GS、借出量、到期日、状态、操作按钮
  • UI 状态映射合约 RepayStatus 枚举:
    • NotDue → 正常（未到期，禁用「还款」按钮）
    • NotDue 且距到期 < 30 天 → 临近到期（BR-10 前端规则）
    • Repayable → 可还款（在还款窗口内）
    • Overdue → 已逾期（可被清算）
    • Repaid / Liquidated → 已结清 / 已清算（默认不显示在"我的订单"主列表）

FR-2 Swap 兑换

FR-2.1代币兑换
支持 GS ⇄ GC 和 GB ⇄ GC 两个交易对的双向兑换。
  • 用户输入 From 数量，系统实时计算 To 数量（来自 Router.getAmountsOut）
  • 兑换前需授权 From 代币
  • 支持反转兑换方向
FR-2.2滑点与价格影响
  • 用户可设置滑点：0.1% / 0.5% / 1.0% / 自定义（参见 BR-8）
  • 系统显示价格影响（Price Impact），> 3% 时高亮警告
  • 展示最小获得量、手续费（参见 BR-9）、路由路径

FR-3 水龙头

FR-3.1测试币领取
新用户连接钱包后可一键领取测试代币（GS / GB / GC 各一份）。
  • 受 BR-5 冷却时间约束（24h/地址）
  • 每次领取量由 BR-6 定义
  • 由服务端持私钥签名转账，无需用户支付 gas
  • 领取成功后展示 3 笔 TX Hash，可跳转区块链浏览器
FR-3.2冷却状态显示
若用户在冷却期内访问，显示倒计时（HH:MM:SS）并禁用领取按钮。

FR-4 仪表盘数据展示

FR-4.1协议统计
Dashboard 展示协议全局只读数据：
  • GS 总质押量、GB 总借出量、GC 总借出量
  • GS/GC、GB/GC 实时价格（来自 UniswapV2 Pair 储备量计算）
  • 当前 GC 利率
  • 网络状态指示灯（区块号、链通畅度）
FR-4.2用户资产 / 持久 Balances
连接钱包后，左侧边栏持久卡片显示 GS / GB / GC 余额，所有页面常驻可见。 未连接时显示插画 + Connect Wallet 引导。

FR-5 钱包连接与会话

FR-5.1连接钱包
支持 MetaMask（桌面）+ WalletConnect v2 兼容钱包（移动端：imToken、TokenPocket 等）。
FR-5.2网络检测与切换
  • 连接时检测 ChainID，非目标网络时显示横幅提示 + 一键切换按钮
  • 切换网络时自动添加网络配置（若用户钱包未配置）

📐5. 业务规则（Business Rules）

ID规则取值来源
BR-1 质押率 70%（借出量 = 质押 GS 价值 × 70%） 合约硬编码
BR-2 借出类型 GB（无息）/ GC（有利率）。对应合约枚举 LoanType { GB = 0, GC = 1 } 合约定义
BR-3 质押周期 360 天 / 720 天 / 1080 天 合约枚举
BR-4 清算分配 清算人获得订单质押 GS 的 1%（liquidationRewardRate = 1e16，admin 可配），剩余 99% 销毁（GS 通过 burnFrom 销毁，不进入"财库"） 合约硬编码 + 管理员可调
BR-5 水龙头冷却 每个地址每 24 小时可领取一次 服务端逻辑
BR-6 水龙头领取量 GS 1,000 · GB 500 · GC 500（可配） .env.local
BR-7 GC 利率来源 调用 TriggerParams.getGCDailyRate() 读取 GC 日利率。
算法：iL = EMA(Rt, 180) + K × σr，其中:
· Rt = GB 日利率（由 GBMarket 写入）
· σr = √(EMA(Rt², 180) − EMA(Rt, 180)²)
· K = 上浮系数（默认 0.5，admin 可调）
注：开仓时利率被固化到订单 gcDailyRate，订单存续期内不再变化。开仓预览页通过 getGCDailyRate 实时读取。 		合约
BR-8 Swap 默认滑点 0.5%，可选 0.1% / 0.5% / 1.0% / 自定义 前端默认
BR-9 Swap 手续费 0.3% UniswapV2 标准
BR-10 临近到期阈值 距到期 < 30 天 时订单状态显示「临近到期」（前端 UI 规则，与合约 RepayStatus 枚举无关） 前端规则
BR-11 还款时间窗口 只能在 [repayDueDate, repayDeadline] 内还款。
· repayDueDate = 开仓次日 UTC 0 点 + cycleDays
· repayDeadline = repayDueDate + gracePeriodDays
· 提前还款被合约 revert（"not due yet"）
· 超过 repayDeadline 不可还款，自动进入可清算状态 		合约硬编码
BR-12 还款宽限期 GB / GC 各自独立，默认均为 30 天（gbGracePeriodDays / gcGracePeriodDays，admin 可调） 合约状态变量
BR-13 GC 利息计算 T+1 起息（开仓次日开始计息），
利息 = gcDailyRate × 计息天数 × debtAmount，
其中 gcDailyRate 在开仓时固化于订单 		合约逻辑
BR-14 担保率计算 · GB:(gsAmount × GS/GB) ÷ debtAmount
· GC:(gsAmount × EMA(GS/GC,5)) ÷ (debtAmount + 实时利息)
· 汇率来自 TriggerParams.getGSGB() / getGSGC5() 		合约逻辑
规则变更管理：BR-1、BR-2、BR-3、BR-7、BR-9、BR-11、BR-13、BR-14 由合约决定，DApp 不可单独修改； BR-4、BR-12 在合约中由 admin 可调；BR-5、BR-6、BR-8、BR-10 是产品/前端规则，可在配置或代码中调整。

🛡️6. 非功能需求（Non-Functional Requirements）

NFR-1兼容性
  • 桌面浏览器：Chrome / Edge / Firefox / Safari 最近两个大版本
  • 钱包：MetaMask（桌面/移动） + WalletConnect v2 协议钱包（imToken、TokenPocket、Trust Wallet 等）
  • 不支持 IE
NFR-2国际化
  • 支持 中文（默认） / English 双语切换
  • 语言选择持久化到 localStorage
  • URL 路径前缀方案：/zh/... / /en/...
  • 数字 / 日期格式化随语言变化
NFR-3移动端适配
  • 响应式布局，断点 sm / md / lg
  • 桌面端左侧 sidebar，移动端 < 768px 收起为底部 Tab Bar
  • 触摸优化：按钮最小高度 44px，输入框字体 16px（防 iOS 自动缩放）
  • 表格在窄屏支持横向滚动
NFR-4安全
  • 水龙头私钥 仅存于服务端 .env.local，不带 NEXT_PUBLIC_ 前缀，永不注入客户端 bundle
  • 所有合约调用必须由用户钱包签名，前端绝不持有用户私钥
  • 用户输入金额必须经过 BigInt 安全转换，避免精度丢失或溢出
  • 显示 TX Hash 链接必须经过白名单浏览器域名校验
NFR-5性能与可用性
  • 首屏 LCP < 2.5s（4G 网络）
  • 合约读调用使用 TanStack Query 缓存，避免重复请求
  • 余额、价格、订单数据自动轮询（间隔 ≥ 10s）或在交易确认后刷新
  • 网络异常时显示明确错误提示，不阻塞页面浏览
NFR-6可观测性
  • 关键交易（开仓、还款、清算、Swap）成功 / 失败有 Toast 提示
  • 错误信息区分：用户取消、余额不足、合约 revert、网络错误，给出针对性提示
  • 水龙头服务端记录每次发放（时间、地址、金额、TX Hash），便于审计

✅7. 验收标准（Acceptance Criteria）

每个功能需求的「完成定义」(Definition of Done)。验收时按以下清单逐项检查。

AC-FR-1质押借贷 - 验收
  • 能在 GB / GC 两种类型间切换，UI 正确显示「无利息」或实时利率
  • 360 / 720 / 1080 周期按钮可点击，选中状态视觉清晰
  • 输入 GS 数量后，可借出量按 70% 实时计算正确
  • 授权额度不足时显示「授权」按钮，足够时直接显示「开仓」
  • 开仓成功后订单出现在「我的订单」列表，数据与合约一致
  • 补仓 / 还款 / 清算 三种操作均能成功上链并刷新订单状态
AC-FR-2Swap 兑换 - 验收
  • GS ⇄ GC、GB ⇄ GC 两个交易对均可正常兑换
  • From 输入数量后，To 数量在 500ms 内更新
  • 价格影响 > 3% 时显示红色警告，用户需二次确认
  • 滑点设置生效（实际成交价偏差超过设置时交易 revert）
  • 授权 → 兑换 两步流程在已授权时跳过授权步骤
AC-FR-3水龙头 - 验收
  • 新地址首次领取，钱包内收到 1000 GS / 500 GB / 500 GC（按 BR-6）
  • 同地址 24h 内再次请求返回 429，显示倒计时
  • 3 笔 TX Hash 可点击跳转 GSCScan 浏览器查看
  • 水龙头钱包余额不足时返回友好错误，提示联系管理员
  • 无效地址（格式错误）返回 400
AC-FR-4仪表盘 - 验收
  • 未连接钱包时，协议统计数据仍可查看（只读模式）
  • 连接钱包后，左侧 Balances 卡片显示三种代币余额
  • 价格数据从 Pair 储备量计算正确，与区块链浏览器一致
  • 网络异常时统计区域显示「数据加载失败」而非空白
AC-FR-5钱包连接 - 验收
  • MetaMask 在桌面端可一键连接
  • WalletConnect v2 二维码可被 imToken / TokenPocket 扫码识别
  • 错误网络时显示横幅 + 一键切换按钮，点击后自动添加 GSC V2 网络配置
  • 断开连接后所有用户态数据（余额、订单）从界面清除

🚫8. 范围之外（Out of Scope）

以下需求 v1.0 不实现，留待后续版本或不实现：

项原因后续计划
合约部署与升级管理面板运维范畴，由合约工程师用脚本完成不计划
LP 流动性挖矿、添加 / 移除流动性合约暂未提供 LP 激励v2.0 候选
治理投票协议无 DAO 治理设计不计划
跨链桥仅服务 Genesis Chain不计划
K 线 / 历史价格图表需要索引服务 + 后端，v1.0 不投入v1.x 候选
清算机器人 / 自动化清算清算逻辑面向人工触发，效率足够v2.0 候选
邮件 / Push 通知（到期、清算预警）需要后端用户系统v2.0 候选
GS DeFi DApp 产品需求文档（PRD）v1.0 · 2026-05-15 · Genesis Chain V2 Testnet
配套设计文档：2026-05-15-dapp-design.html