# 工单 #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=` - 全局搜索（区块/交易/地址） **数据来源**： - 直接连接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必须支持**： - NRPC4.0协议 - 所有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共识、NRPC4.0协议） 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 (新端口) │ │ 协议: NRPC4.0 │ └─────────────────────────────────────┘ │ ├─► 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端口标准文档 - NRPC4.0协议规范 - 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周)