387 lines
8.8 KiB
Markdown
387 lines
8.8 KiB
Markdown
# 工单 #005：完整API服务器实现与全系统真实数据切换
|
||
|
||
**创建日期**: 2026-02-20
|
||
**优先级**: 🔴 最高
|
||
**状态**: 📋 进行中
|
||
**负责人**: NAC技术团队
|
||
|
||
---
|
||
|
||
## 问题描述
|
||
|
||
当前NAC主网虽然已上线，但存在严重问题：
|
||
|
||
### 核心问题
|
||
1. **API服务器不完整**
|
||
- 现有API服务器只有 `/health` 端点
|
||
- 缺少 `/blocks`, `/transactions`, `/addresses`, `/stats` 等核心端点
|
||
- 无法提供真实的区块链数据
|
||
|
||
2. **所有前端使用模拟数据**
|
||
- 量子浏览器：显示模拟数据（区块12,345，交易1,234,567）
|
||
- 监控页面：部分使用模拟数据
|
||
- 钱包：可能使用模拟数据
|
||
- SDK：未与真实API对接
|
||
|
||
3. **主网已上线但无法查询**
|
||
- 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**：
|
||
1. **JavaScript SDK** (`nac-sdk-js`)
|
||
- 更新API端点
|
||
- 添加新的方法
|
||
- 更新文档
|
||
|
||
2. **Go SDK** (`nac-sdk-go`)
|
||
- 更新API客户端
|
||
- 添加新的接口
|
||
|
||
3. **Python SDK** (`nac-sdk-python`)
|
||
- 更新API封装
|
||
- 添加新的类和方法
|
||
|
||
**SDK必须支持**：
|
||
- NAC Lens协议
|
||
- 所有API端点
|
||
- 错误处理
|
||
- 重试机制
|
||
- WebSocket支持（实时数据）
|
||
|
||
---
|
||
|
||
### 阶段3：修改量子浏览器
|
||
|
||
**当前问题**：
|
||
```javascript
|
||
// 硬编码的模拟数据
|
||
totalBlocks: 12345
|
||
totalTransactions: 1234567
|
||
activeAddresses: 5678
|
||
rpcUrl: "/api/" // 错误的相对路径
|
||
consensus: "DAG" // 错误，应该是CBPP
|
||
```
|
||
|
||
**修改内容**：
|
||
1. 移除所有模拟数据
|
||
2. 使用真实API：`https://api.newassetchain.io`
|
||
3. 实时获取区块、交易、地址数据
|
||
4. 修正技术信息（CBPP共识、NAC Lens协议）
|
||
5. 添加实时更新（WebSocket）
|
||
|
||
**必须实现的功能**：
|
||
- 首页：实时统计数据
|
||
- 区块列表：真实区块数据
|
||
- 区块详情：完整区块信息
|
||
- 交易列表：真实交易数据
|
||
- 交易详情：完整交易信息
|
||
- 地址查询：地址余额和交易历史
|
||
- 搜索功能：全局搜索
|
||
|
||
---
|
||
|
||
### 阶段4：修改监控页面
|
||
|
||
**当前问题**：
|
||
- 区块高度需要手动刷新
|
||
- 缺少详细的模块状态
|
||
- 缺少实时图表
|
||
|
||
**修改内容**：
|
||
1. 使用真实API获取数据
|
||
2. 实时更新（WebSocket）
|
||
3. 添加图表（区块生产速度、交易量、TPS）
|
||
4. 添加告警功能
|
||
5. 添加历史数据查看
|
||
|
||
---
|
||
|
||
### 阶段5：修改钱包
|
||
|
||
**检查项**：
|
||
1. 钱包是否存在？
|
||
2. 钱包使用什么数据源？
|
||
3. 是否使用模拟数据？
|
||
|
||
**修改内容**（如果需要）：
|
||
1. 连接到真实API
|
||
2. 使用真实余额
|
||
3. 真实交易提交
|
||
4. 交易历史查询
|
||
|
||
---
|
||
|
||
### 阶段6：其他系统检查
|
||
|
||
**需要检查的系统**：
|
||
1. RWA资产管理系统
|
||
2. 宪法治理系统
|
||
3. 开发者工具
|
||
4. 文档网站
|
||
|
||
---
|
||
|
||
## 技术架构
|
||
|
||
### 新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：开发时间不足
|
||
**影响**: 高
|
||
**概率**: 中
|
||
**应对**:
|
||
- 优先实现核心功能
|
||
- 分阶段发布
|
||
- 必要时增加人力
|
||
|
||
### 风险3：性能问题
|
||
**影响**: 中
|
||
**概率**: 低
|
||
**应对**:
|
||
- 使用缓存（Redis）
|
||
- 建立索引数据库
|
||
- 优化查询
|
||
|
||
### 风险4：兼容性问题
|
||
**影响**: 中
|
||
**概率**: 低
|
||
**应对**:
|
||
- 保持向后兼容
|
||
- 提供迁移指南
|
||
- 充分测试
|
||
|
||
---
|
||
|
||
## 依赖关系
|
||
|
||
```
|
||
工单#005 (本工单)
|
||
├─► 依赖: 工单#001 (端口标准化) ✅
|
||
├─► 依赖: 工单#002 (模块验证) ✅
|
||
└─► 阻塞: 工单#006 (前端优化)
|
||
```
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- NAC端口标准文档
|
||
- NAC Lens协议规范
|
||
- CBPP共识协议文档
|
||
- ACC-20资产标准
|
||
- Charter智能合约语言规范
|
||
- CNNL宪法语言规范
|
||
|
||
---
|
||
|
||
## 进度追踪
|
||
|
||
### 当前状态: 📋 进行中
|
||
|
||
**已完成**:
|
||
- [x] 问题分析
|
||
- [x] 解决方案设计
|
||
- [x] 工单创建
|
||
|
||
**进行中**:
|
||
- [ ] API服务器开发
|
||
- [ ] SDK更新
|
||
- [ ] 前端系统更新
|
||
|
||
**待办**:
|
||
- [ ] 测试
|
||
- [ ] 部署
|
||
- [ ] 文档
|
||
- [ ] 验收
|
||
|
||
---
|
||
|
||
## 备注
|
||
|
||
**重要提醒**:
|
||
1. 这是NAC主网的核心基础设施，必须100%完成
|
||
2. 不能使用任何模拟数据，必须是真实数据
|
||
3. 不能使用快速或简化方式，必须完整实现
|
||
4. 所有修改必须经过充分测试
|
||
5. 必须保持向后兼容
|
||
6. 必须有完整的文档
|
||
|
||
**后续工单**:
|
||
- 工单#006: 前端系统优化和用户体验提升
|
||
- 工单#007: Charter编译器完整功能实现
|
||
- 工单#008: CNNL编译器完整功能实现
|
||
- 工单#009: 钱包功能完善
|
||
- 工单#010: RWA资产管理系统
|
||
|
||
---
|
||
|
||
**创建人**: NAC技术团队
|
||
**创建时间**: 2026-02-20
|
||
**最后更新**: 2026-02-20
|
||
**预计完成时间**: 2026-03-20 (4周)
|