8.8 KiB

Raw Blame History

工单 #005：完整API服务器实现与全系统真实数据切换

创建日期: 2026-02-20
优先级: 🔴 最高
状态: 📋 进行中
负责人: NAC技术团队

问题描述

当前NAC主网虽然已上线，但存在严重问题：

核心问题

API服务器不完整
- 现有API服务器只有 /health 端点
- 缺少 /blocks, /transactions, /addresses, /stats 等核心端点
- 无法提供真实的区块链数据
所有前端使用模拟数据
- 量子浏览器：显示模拟数据（区块12,345，交易1,234,567）
- 监控页面：部分使用模拟数据
- 钱包：可能使用模拟数据
- SDK：未与真实API对接
主网已上线但无法查询
- CBPP共识节点正常运行（区块高度20,000+）
- 但外部无法查询区块、交易等数据
- 用户无法验证链上数据

解决方案

阶段1：创建完整的NAC API服务器

技术选型: Go语言 + Gin框架

必须实现的端点：

1. 基础信息端点

GET /health - 健康检查（已有）
GET /info - 链信息（chain_id, network, version）
GET /stats - 统计信息（总区块数、总交易数、活跃地址数）

2. 区块端点

GET /blocks - 区块列表（分页）
GET /blocks/:height - 根据高度查询区块
GET /blocks/:hash - 根据哈希查询区块
GET /blocks/latest - 最新区块
GET /blocks/:height/transactions - 区块内的交易列表

3. 交易端点

GET /transactions - 交易列表（分页）
GET /transactions/:hash - 根据哈希查询交易
GET /transactions/pending - 待处理交易
POST /transactions - 提交交易

4. 地址端点

GET /addresses/:address - 地址信息
GET /addresses/:address/balance - 地址余额
GET /addresses/:address/transactions - 地址交易历史
GET /addresses/:address/assets - 地址资产列表

5. 合约端点

GET /contracts/:address - 合约信息
POST /contracts/call - 调用合约
GET /contracts/:address/events - 合约事件

6. 资产端点（ACC-20）

GET /assets - 资产列表
GET /assets/:id - 资产详情
GET /assets/:id/holders - 资产持有者

7. 宪法端点（CNNL）

GET /constitution - 当前宪法
GET /constitution/history - 宪法历史
GET /constitution/proposals - 宪法提案

8. 搜索端点

GET /search?q=<query> - 全局搜索（区块/交易/地址）

数据来源：

直接连接CBPP节点（端口9545）
读取NVM节点数据（端口9549）
可选：建立索引数据库（PostgreSQL）

阶段2：调整SDK

需要更新的SDK：

JavaScript SDK (nac-sdk-js)
- 更新API端点
- 添加新的方法
- 更新文档
Go SDK (nac-sdk-go)
- 更新API客户端
- 添加新的接口
Python SDK (nac-sdk-python)
- 更新API封装
- 添加新的类和方法

SDK必须支持：

NAC Lens协议
所有API端点
错误处理
重试机制
WebSocket支持（实时数据）

阶段3：修改量子浏览器

当前问题：

// 硬编码的模拟数据
totalBlocks: 12345
totalTransactions: 1234567
activeAddresses: 5678
rpcUrl: "/api/"  // 错误的相对路径
consensus: "DAG"  // 错误，应该是CBPP

修改内容：

移除所有模拟数据
使用真实API：https://api.newassetchain.io
实时获取区块、交易、地址数据
修正技术信息（CBPP共识、NAC Lens协议）
添加实时更新（WebSocket）

必须实现的功能：

首页：实时统计数据
区块列表：真实区块数据
区块详情：完整区块信息
交易列表：真实交易数据
交易详情：完整交易信息
地址查询：地址余额和交易历史
搜索功能：全局搜索

阶段4：修改监控页面

当前问题：

区块高度需要手动刷新
缺少详细的模块状态
缺少实时图表

修改内容：

使用真实API获取数据
实时更新（WebSocket）
添加图表（区块生产速度、交易量、TPS）
添加告警功能
添加历史数据查看

阶段5：修改钱包

检查项：

钱包是否存在？
钱包使用什么数据源？
是否使用模拟数据？

修改内容（如果需要）：

连接到真实API
使用真实余额
真实交易提交
交易历史查询

阶段6：其他系统检查

需要检查的系统：

RWA资产管理系统
宪法治理系统
开发者工具
文档网站

技术架构

新API服务器架构

┌─────────────────────────────────────┐
│   NAC API Server (Go + Gin)        │
│   端口: 9551 (新端口)                │
│   协议: NAC Lens                     │
└─────────────────────────────────────┘
           │
           ├─► CBPP节点 (端口9545)
           ├─► NVM节点 (端口9549)
           ├─► PostgreSQL (索引数据库)
           └─► Redis (缓存)

数据流

CBPP节点 ──► API服务器 ──► 前端系统
   │                        │
   │                        ├─► 量子浏览器
   │                        ├─► 监控页面
   │                        ├─► 钱包
   │                        └─► SDK
   │
   └─► 索引器 ──► PostgreSQL

实施计划

Week 1: API服务器开发

Day 1-2: 基础框架和核心端点
Day 3-4: 区块和交易端点
Day 5: 地址和合约端点
Day 6: 测试和优化
Day 7: 部署和文档

Week 2: SDK更新

Day 1-2: JavaScript SDK
Day 3: Go SDK
Day 4: Python SDK
Day 5-6: 测试和文档
Day 7: 发布新版本

Week 3: 前端系统更新

Day 1-3: 量子浏览器
Day 4-5: 监控页面
Day 6: 钱包（如果需要）
Day 7: 测试和部署

Week 4: 测试和优化

Day 1-3: 全系统集成测试
Day 4-5: 性能优化
Day 6: 文档更新
Day 7: 最终验收

验收标准

API服务器

所有端点正常工作
返回真实数据（非模拟）
响应时间 < 100ms (95th percentile)
支持每秒1000+请求
完整的API文档

SDK

所有方法正常工作
完整的类型定义
完整的文档和示例
单元测试覆盖率 > 80%

量子浏览器

无模拟数据
所有页面显示真实数据
实时更新正常
搜索功能正常
响应速度快

监控页面

实时数据更新
图表显示正常
告警功能正常
历史数据查看正常

钱包

余额显示正确
交易提交成功
交易历史正确
资产管理正常

风险与应对

风险1：CBPP节点数据格式未知

影响: 高
概率: 中
应对:

先分析CBPP节点日志和输出
如果无法直接读取，考虑建立索引器
最坏情况：修改CBPP节点代码添加API

风险2：开发时间不足