petrogold mvp 的指南
# PetroGold Super App — 完整项目交接文档
> **文档版本**: v1.0.0 — Production Ready
> **创建日期**: 2026-06-12
> **文档性质**: 正式交接文件 · 可直接用于团队 Onboarding
> **适用对象**: 接手开发者 / 产品经理 / 审计方 / 部署工程师
> **文件状态**: ✅ 已完成 R&D 阶段 → 进入生产部署阶段
---
## 目录
```
PART 1 — 项目全景与定位
PART 2 — 产品规格书 (PRD)
PART 3 — 文件结构与模块说明
PART 4 — 核心参数配置手册（可随时调节）
PART 5 — 模块间通信协议 (PostMessage API)
PART 6 — 部署指南（从零到上线）
PART 7 — 注意事项 & 已知风险
PART 8 — QnA 常见问题
PART 9 — 逻辑细节推理与架构决策
PART 10 — 升级 & Debug 操作手册（小白友好）
PART 11 — 路线图与未来迭代建议
```
---
# PART 1 — 项目全景与定位
## 1.1 一句话定义
**PetroGold** 是一套 **以实物黄金为信任锚点、区块链为结算层、AI 为配置引擎** 的数字经济超级应用（Super App）。它以 **微前端架构** 构建，由 11 个独立 Single-HTML 模块 + 1 个主控 Frame 组成，可作为：
- 💼 **融资演示工具**（面向投资人）
- 🛠️ **可部署 Web App**（面向用户）
- 🧪 **沙盒参数实验室**（面向开发团队）
## 1.2 项目当前阶段
```
阶段 状态
──────────────────────────────────────────
设计 & 原型 ✅ 已完成（不可逆）
R&D 模块开发 ✅ 已完成（11个模块全交付）
集成 & 框架搭建 ✅ Frame.html 完成
参数可调性 ✅ 全部关键参数已暴露为变量
生产部署 🚀 待执行（指南见 PART 6）
真实合约集成 ⏳ 需 Solidity 工程师接手
后端 API 对接 ⏳ 需后端工程师对接
```
## 1.3 核心竞争优势（对标分析）
| 竞品 | 优势 | PetroGold 超越点 |
|------|------|-----------------|
| PAX Gold (PAXG) | LBMA 信任 | +生息/借贷/DAO/AI/支付 |
| Tether Gold (XAUT) | Tether 品牌 | +链上实时 PoR/ZK 合规 |
| Meld Gold | 供应链溯源 | +C端 App / 稳定币 / AI 配置 |
| 传统黄金 ETF | 机构通道 | +碎股化/$0.01 门槛/24/7 |
---
# PART 2 — 产品规格书 (PRD)
## 2.1 核心代币体系
### PETRO（核心资产代币）
```
类型: ERC-20 on Polygon PoS
锚定: 1 PETRO = 1 克实物 LBMA 黄金
精度: 18 位小数（最小单位 0.000001g）
合约地址: 0xB8ec591828832EBB41975a43c394153f43e2C2b3 (现有)
铸造权限: MINTER_ROLE + 多签 + 托管 API 回执
销毁机制: BurnRequested → BurnFulfilled 双阶段
供应约束: 链上总供应 ≤ 托管商报告库存（PoR 约束）
```
### GCASH（黄金超额抵押稳定币）
```
类型: ERC-20，软锚定 $1 USD
抵押品: PETRO / GOLD（超额抵押）
最低抵押率: 150%（可调参数 → 见 PART 4）
清算阈值: 130%（可调参数）
清算奖励: 5-10%（可调参数）
稳定费: 0.75% / 年（可调参数）
铸造上限: 托管黄金市值 × 60%（可调参数）
合约: CollateralVault.sol（待部署）
```
### pgvGOLD（生息凭证代币）
```
类型: 收益型 ERC-20（价值随时间递增）
存入比例: 1:1 存入 PETRO，获得 pgvGOLD
兑换率: pgvRate = 1 + (APY × 已过天数 / 365)
APY 范围: 2.50% ~ 5.50%（按锁仓期分档）
锁仓档位: 灵活(0天) / 30天 / 90天 / 180天
合约: StakingVault.sol（待部署）
```
### vePETRO（治理锁仓凭证）
```
类型: 非转让 ERC-721（灵魂绑定）
获取方式: 锁仓 PETRO × 权重乘数
权重乘数: 3月×1.0 / 6月×1.5 / 1年×2.0 / 4年×4.0
用途: PetroDAO 投票权 + 协议收益分享
```
## 2.2 费率参数总表（均可通过 PART 4 调节）
| 参数名 | 当前值 | 最小值 | 最大值 | 说明 |
|--------|--------|--------|--------|------|
| MINT_FEE | 0.15% | 0.01% | 2.00% | 铸造手续费 |
| BURN_FEE | 0.25% | 0.01% | 2.00% | 赎回手续费 |
| STABILITY_FEE | 0.75%/yr | 0.10% | 5.00% | GCASH 稳定费 |
| MIN_COLLATERAL_RATIO | 150% | 120% | 300% | 最低抵押率 |
| LIQUIDATION_THRESHOLD | 130% | 110% | 200% | 清算触发阈值 |
| LIQUIDATION_REWARD | 7.5% | 2% | 15% | 清算人奖励 |
| MAX_GCASH_MINT_CAP | 60% | 30% | 80% | GCASH铸造上限/储备 |
| VAULT_APY_FLEXIBLE | 2.50% | 0.50% | 8.00% | 灵活档 APY |
| VAULT_APY_30D | 3.20% | 1.00% | 10.00% | 30天档 APY |
| VAULT_APY_90D | 4.10% | 1.50% | 12.00% | 90天档 APY |
| VAULT_APY_180D | 5.50% | 2.00% | 15.00% | 180天档 APY |
| VELOCK_3M_MULTIPLIER | 1.0× | 1.0× | 2.0× | vePETRO 3月乘数 |
| VELOCK_6M_MULTIPLIER | 1.5× | 1.0× | 3.0× | vePETRO 6月乘数 |
| VELOCK_1Y_MULTIPLIER | 2.0× | 1.5× | 4.0× | vePETRO 1年乘数 |
| VELOCK_4Y_MULTIPLIER | 4.0× | 2.0× | 8.0× | vePETRO 4年乘数 |
| UBI_MAX_RATIO | 30% | 5% | 50% | UBI占协议收入上限 |
## 2.3 KYC 分级权限
| 等级 | 日限额 | 铸造 | 赎回 | 借贷 | 治理 |
|------|--------|------|------|------|------|
| L0 | 只读 | ❌ | ❌ | ❌ | ❌ |
| L1 | $1,000 | ✅ | ✅ | ❌ | ✅ |
| L2 | $50,000 | ✅ | ✅ | ✅ | ✅ |
| L3 (机构) | 无限 | ✅ | ✅ | ✅ | ✅ |
---
# PART 3 — 文件结构与模块说明
## 3.1 完整文件清单
```
PetroGold_SuperApp/
│
├── Frame.html ← 主控外壳（必须首先运行）
│
├── Roadshow_Main.html ← 模块①: 投资人路演
├── Product_Mint.html ← 模块②: 黄金铸造/赎回
├── Product_Stake.html ← 模块③: 生息金库
├── GCASH_Vault.html ← 模块④: GCASH借贷
├── GoldPay_Demo.html ← 模块⑤: 支付功能
├── Live_Demo.html ← 模块⑥: 链上沙盒演示
├── Reserve_PoR.html ← 模块⑦: 储备证明
├── Ecosystem_DAO.html ← 模块⑧: 治理系统
├── Interactive_Roadmap.html ← 模块⑨: 路线图
├── AI_Treasury.html ← 模块⑩: AI配置引擎
│
└── PETROGOLD_MASTER_HANDOVER.md ← 本文档
```
## 3.2 每个模块详细说明
---
### 🎯 Frame.html — 主控外壳
**职责**: 整个 App 的入口和路由器。不包含任何业务逻辑，只负责调度。
**核心功能**:
- Boot Sequence 启动动画（三环轨道 Logo）
- iOS 风格状态栏 + 实时时钟
- 主标题栏（Logo + 金价 + 通知 + 汉堡菜单）
- 二级 SubNav（每个模块专属子标签）
- `