# NAC钱包系统关联集成交付报告

**日期**: 2026-02-26
**工单**: 注册系统 + 钱包模块 + 一键上链系统关联集成
**状态**: 100% 完成

---

## 一、本次工作概述

本次工作实现了NAC公链三大核心系统的完整关联：

- 注册系统 (id.newassetchain.io) -- 注册时自动创建NAC原生钱包
- NAC钱包微服务 (nac-wallet-service, 端口8701) -- 上链时调用钱包签名 + XIC手续费计算
- 一键上链系统 (onboarding.newassetchain.io)

---

## 二、技术架构

### 双币模式
- **XIC（资产治理币）**：可从交易所购买，用于支付所有平台手续费（默认）
- **XTZH（资产稳定币）**：需要铸造，用于资产计价和结算

### 手续费机制
- 所有手续费默认以 **XIC** 支付
- 持有XIC数量越多，享受更高折扣（VIP等级制度）
- 管理员可通过后台动态调整费率（前期推广可设为0）

### 数据库
- **PostgreSQL 14**（钱包专用数据库）：nac_wallet
- **MySQL**（PHP注册系统）：nac_auth
- **MongoDB**（一键上链系统）

---

## 三、新增/修改文件清单

### 新增文件

| 文件路径 | 说明 |
|---------|------|
| /opt/nac/nac_wallet_service/ | Rust钱包微服务（Actix-Web + PostgreSQL） |
| /opt/nac/onboarding/backend/nac_wallet_client.py | Python钱包客户端（供onboarding调用） |
| /var/www/id.newassetchain.io/app/Services/NacWalletService.php | PHP钱包客户端（供Laravel调用） |

### 修改文件

| 文件路径 | 修改内容 |
|---------|---------|
| /var/www/id.newassetchain.io/app/Http/Controllers/AuthController.php | 注册时自动调用钱包微服务创建NAC钱包 |
| /var/www/id.newassetchain.io/resources/views/auth/success.blade.php | 注册成功页面展示钱包地址和助记词 |
| /opt/nac/onboarding/backend/routers/users.py | 注册时自动创建NAC钱包 |
| /opt/nac/onboarding/backend/routers/onboarding.py | chain-confirm步骤集成钱包签名和XIC手续费 |

---

## 四、测试结果

### 4.1 PHP注册系统（id.newassetchain.io）
- [PASS] 注册API：返回钱包地址 + 双币余额 + 12个助记词
- [PASS] 登录API：正常返回JWT token
- [PASS] 钱包查询API：返回XIC和XTZH余额
- [PASS] 前端UI：注册成功页面正确展示助记词（仅一次）

### 4.2 一键上链系统（onboarding.newassetchain.io）
- [PASS] 注册API：返回钱包地址 + 双币余额 + 12个助记词
- [PASS] chain-confirm步骤：集成XIC手续费估算 + 钱包签名（降级安全处理）

### 4.3 钱包微服务（内网8701端口）
- [PASS] 健康检查：status=healthy, database=connected
- [PASS] 创建钱包：生成NAC原生32字节地址 + 加密助记词
- [PASS] 手续费配置：支持管理员动态调整
- [PASS] 安全认证：内部API密钥验证

---

## 五、安全措施

1. **私钥安全**：助记词使用AES-256-GCM加密存储，服务器上永无明文
2. **助记词一次性**：仅注册时返回一次，系统不再存储明文
3. **内网通信**：钱包微服务仅监听127.0.0.1:8701，不对外网暴露
4. **API密钥认证**：服务间调用使用内部密钥验证
5. **代码安全**：Rust禁止unsafe，PHP使用PDO预处理，所有密钥通过.env注入

---

## 六、未来扩展

本架构已为以下功能预留接口：
- 交易所模块（XIC/USDT、XIC/USDC交易对）
- 中间链和跨链桥
- 移动端App（安卓/苹果）
- PC端域名化（wallet.newassetchain.io）
- 多语言支持（i18n）

---

## 七、关联工单

- 工单 #33：钱包后台管理系统
- 工单 #34：VISION智能钱包
- 工单 #35：多链支持
- 工单 #37：一键上链关联