574 lines
12 KiB
Markdown
574 lines
12 KiB
Markdown
# NAC一键上链系统 - API调用实现方案
|
||
|
||
## 核心理念
|
||
|
||
**所有9个模块都通过调用已有的API接口实现，不重新开发底层功能。**
|
||
|
||
---
|
||
|
||
## 模块1: 编排引擎
|
||
|
||
**职责**: 协调各模块API调用，管理状态机
|
||
|
||
**实现方式**:
|
||
- 状态机管理（本地实现）
|
||
- 调用其他8个模块的API
|
||
- 错误处理和重试（本地实现）
|
||
|
||
**代码位置**: `src/services/orchestrator.rs`
|
||
|
||
---
|
||
|
||
## 模块2: AI合规审批模块
|
||
|
||
**API调用**: `nac-sdk` → `L4适配器` → `nac-ai-compliance`
|
||
|
||
**调用方式**:
|
||
```rust
|
||
use nac_sdk::adapters::NACAdapter;
|
||
|
||
let adapter = NACAdapter::new(&config).await?;
|
||
|
||
// 调用AI合规审批
|
||
let compliance_result = adapter.l4()
|
||
.compliance_check(asset_type, legal_docs, kyc_level, jurisdiction)
|
||
.await?;
|
||
```
|
||
|
||
**返回数据**:
|
||
- 合规性评分
|
||
- 审批结果哈希
|
||
- 证明数据
|
||
|
||
**代码位置**: `src/services/compliance.rs`
|
||
|
||
---
|
||
|
||
## 模块3: AI估值模块
|
||
|
||
**API调用**: `nac-sdk` → `L4适配器` → `nac-ai-valuation`
|
||
|
||
**调用方式**:
|
||
```rust
|
||
// 调用AI估值
|
||
let valuation_result = adapter.l4()
|
||
.asset_valuation(asset_type, market_data, historical_data)
|
||
.await?;
|
||
```
|
||
|
||
**返回数据**:
|
||
- 估值结果（SDR计价）
|
||
- 估值结果哈希
|
||
- 估值模型参数
|
||
|
||
**代码位置**: `src/services/valuation.rs`
|
||
|
||
---
|
||
|
||
## 模块4: DNA生成模块
|
||
|
||
**API调用**: `nac-sdk` → `L1适配器` → `nac-gnacs`
|
||
|
||
**调用方式**:
|
||
```rust
|
||
// 生成GNACS编码
|
||
let gnacs_code = adapter.l1()
|
||
.gnacs_encode(asset_type, risk_weight, compliance_level)
|
||
.await?;
|
||
|
||
// 生成资产DNA
|
||
let dna = create_asset_dna(gnacs_code, asset_info);
|
||
let dna_hash = adapter.l0().hash_sha3_384(&dna)?;
|
||
```
|
||
|
||
**返回数据**:
|
||
- 48位GNACS编码
|
||
- 资产DNA结构
|
||
- DNA哈希
|
||
|
||
**代码位置**: `src/services/dna.rs`
|
||
|
||
---
|
||
|
||
## 模块5: 宪法执行引擎（CEE）
|
||
|
||
**API调用**: `nac-sdk` → `L2适配器` → `nac-constitution`
|
||
|
||
**调用方式**:
|
||
```rust
|
||
// 提交宪法审查
|
||
let cr_compliance = adapter.l2()
|
||
.submit_constitutional_review(compliance_result)
|
||
.await?;
|
||
|
||
// 查询审查结果
|
||
let review_result = adapter.l2()
|
||
.query_review_result(review_id)
|
||
.await?;
|
||
```
|
||
|
||
**返回数据**:
|
||
- 宪法收据（CR）
|
||
- 审查结果
|
||
- 合规证明
|
||
|
||
**代码位置**: `src/services/constitution.rs`
|
||
|
||
---
|
||
|
||
## 模块6: 托管对接模块
|
||
|
||
**API调用**:
|
||
1. `nac-sdk` → `L2适配器` → 获取托管机构白名单
|
||
2. 直接调用托管机构API（HTTPS + 数字签名）
|
||
|
||
**调用方式**:
|
||
```rust
|
||
// 获取托管机构白名单
|
||
let custody_list = adapter.l2()
|
||
.get_custody_whitelist(asset_type, jurisdiction)
|
||
.await?;
|
||
|
||
// 选择托管机构
|
||
let custody_provider = select_custody_provider(&custody_list);
|
||
|
||
// 调用托管机构API
|
||
let custody_receipt = call_custody_api(
|
||
custody_provider,
|
||
asset_dna,
|
||
valuation_result,
|
||
legal_docs
|
||
).await?;
|
||
|
||
// 验证托管凭证
|
||
let verified = adapter.l2()
|
||
.verify_custody_receipt(custody_receipt)
|
||
.await?;
|
||
```
|
||
|
||
**返回数据**:
|
||
- 托管凭证（含数字签名）
|
||
- 托管凭证哈希
|
||
|
||
**代码位置**: `src/services/custody.rs`
|
||
|
||
---
|
||
|
||
## 模块7: XTZH铸造模块
|
||
|
||
**API调用**: `nac-sdk` → `L1适配器` → `nac-xtzh`
|
||
|
||
**调用方式**:
|
||
```rust
|
||
// 计算铸造数量（估值 × 125%）
|
||
let xtzh_amount = valuation_result.value * 1.25;
|
||
|
||
// 铸造XTZH
|
||
let mint_result = adapter.l1()
|
||
.xtzh_mint(
|
||
issuer_address,
|
||
xtzh_amount,
|
||
asset_dna,
|
||
custody_receipt,
|
||
vec![cr_compliance, cr_valuation, cr_dna, cr_custody]
|
||
)
|
||
.await?;
|
||
```
|
||
|
||
**返回数据**:
|
||
- 铸造交易哈希
|
||
- XTZH数量
|
||
- 铸造记录
|
||
|
||
**代码位置**: `src/services/xtzh.rs`
|
||
|
||
---
|
||
|
||
## 模块8: 权益代币发行模块
|
||
|
||
**API调用**: `nac-sdk` → `L1适配器` → `nac-nvm`
|
||
|
||
**调用方式**:
|
||
```rust
|
||
// 选择合约模板
|
||
let template = select_token_template(asset_type);
|
||
|
||
// 部署代币合约
|
||
let contract_address = adapter.l1()
|
||
.deploy_contract(
|
||
template,
|
||
gnacs_code,
|
||
total_supply,
|
||
issuer_address,
|
||
vec![cr_compliance, cr_valuation, cr_dna, cr_custody, cr_xtzh]
|
||
)
|
||
.await?;
|
||
|
||
// 转移代币所有权
|
||
let transfer_result = adapter.l1()
|
||
.acc20_transfer(contract_address, from, to, amount)
|
||
.await?;
|
||
```
|
||
|
||
**返回数据**:
|
||
- 代币合约地址
|
||
- 部署交易哈希
|
||
- 代币信息
|
||
|
||
**代码位置**: `src/services/token.rs`
|
||
|
||
---
|
||
|
||
## 模块9: 链上公示模块
|
||
|
||
**API调用**: `nac-sdk` → `L5适配器` → 浏览器/钱包/交易所API
|
||
|
||
**调用方式**:
|
||
```rust
|
||
// 注册到区块链浏览器
|
||
let browser_result = adapter.l5()
|
||
.register_asset_to_browser(
|
||
gnacs_code,
|
||
contract_address,
|
||
asset_metadata
|
||
)
|
||
.await?;
|
||
|
||
// 推送到钱包
|
||
let wallet_result = adapter.l5()
|
||
.push_token_to_wallet(
|
||
contract_address,
|
||
token_info
|
||
)
|
||
.await?;
|
||
|
||
// 提交交易所上币申请
|
||
let exchange_result = adapter.l5()
|
||
.submit_listing_application(
|
||
contract_address,
|
||
token_info,
|
||
vec![all_crs]
|
||
)
|
||
.await?;
|
||
```
|
||
|
||
**返回数据**:
|
||
- 浏览器注册结果
|
||
- 钱包推送结果
|
||
- 交易所申请结果
|
||
|
||
**代码位置**: `src/services/listing.rs`
|
||
|
||
---
|
||
|
||
## 完整流程示例
|
||
|
||
```rust
|
||
// src/services/orchestrator.rs
|
||
|
||
pub async fn process_asset_onboarding(
|
||
asset_submission: AssetSubmission,
|
||
adapter: &NACAdapter
|
||
) -> Result<OnboardingResult, Error> {
|
||
|
||
// 1. 初始化状态
|
||
let mut state = OnboardingState::Pending;
|
||
|
||
// 2. AI合规审批
|
||
state = OnboardingState::ComplianceCheck;
|
||
let compliance_result = compliance::check(
|
||
&asset_submission,
|
||
adapter
|
||
).await?;
|
||
|
||
// 3. AI估值
|
||
state = OnboardingState::Valuation;
|
||
let valuation_result = valuation::valuate(
|
||
&asset_submission,
|
||
adapter
|
||
).await?;
|
||
|
||
// 4. DNA生成
|
||
state = OnboardingState::DNAGeneration;
|
||
let dna_result = dna::generate(
|
||
&asset_submission,
|
||
&compliance_result,
|
||
&valuation_result,
|
||
adapter
|
||
).await?;
|
||
|
||
// 5. 宪法审查（获取所有CR）
|
||
let crs = constitution::review_all(
|
||
&compliance_result,
|
||
&valuation_result,
|
||
&dna_result,
|
||
adapter
|
||
).await?;
|
||
|
||
// 6. 托管对接
|
||
state = OnboardingState::Custody;
|
||
let custody_result = custody::custody(
|
||
&asset_submission,
|
||
&dna_result,
|
||
&valuation_result,
|
||
adapter
|
||
).await?;
|
||
|
||
// 7. XTZH铸造
|
||
state = OnboardingState::XTZHMinting;
|
||
let xtzh_result = xtzh::mint(
|
||
&asset_submission,
|
||
&valuation_result,
|
||
&dna_result,
|
||
&custody_result,
|
||
&crs,
|
||
adapter
|
||
).await?;
|
||
|
||
// 8. 权益代币发行
|
||
state = OnboardingState::TokenIssuance;
|
||
let token_result = token::issue(
|
||
&asset_submission,
|
||
&dna_result,
|
||
&xtzh_result,
|
||
&crs,
|
||
adapter
|
||
).await?;
|
||
|
||
// 9. 链上公示
|
||
state = OnboardingState::Listed;
|
||
let listing_result = listing::list(
|
||
&asset_submission,
|
||
&dna_result,
|
||
&token_result,
|
||
adapter
|
||
).await?;
|
||
|
||
// 10. 完成
|
||
Ok(OnboardingResult {
|
||
asset_id: asset_submission.id,
|
||
state: OnboardingState::Listed,
|
||
compliance_result,
|
||
valuation_result,
|
||
dna_result,
|
||
custody_result,
|
||
xtzh_result,
|
||
token_result,
|
||
listing_result,
|
||
crs,
|
||
})
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 数据库设计
|
||
|
||
### 表1: assets（资产表）
|
||
|
||
```sql
|
||
CREATE TABLE assets (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
user_id VARCHAR(36) NOT NULL,
|
||
asset_type VARCHAR(50) NOT NULL,
|
||
asset_info JSON NOT NULL,
|
||
legal_docs JSON NOT NULL,
|
||
kyc_level INT NOT NULL,
|
||
jurisdiction VARCHAR(50) NOT NULL,
|
||
state VARCHAR(50) NOT NULL,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
INDEX idx_user_id (user_id),
|
||
INDEX idx_state (state)
|
||
);
|
||
```
|
||
|
||
### 表2: onboarding_records（上链记录表）
|
||
|
||
```sql
|
||
CREATE TABLE onboarding_records (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
asset_id VARCHAR(36) NOT NULL,
|
||
state VARCHAR(50) NOT NULL,
|
||
compliance_result JSON,
|
||
valuation_result JSON,
|
||
dna_result JSON,
|
||
custody_result JSON,
|
||
xtzh_result JSON,
|
||
token_result JSON,
|
||
listing_result JSON,
|
||
crs JSON,
|
||
error_message TEXT,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
FOREIGN KEY (asset_id) REFERENCES assets(id),
|
||
INDEX idx_asset_id (asset_id),
|
||
INDEX idx_state (state)
|
||
);
|
||
```
|
||
|
||
### 表3: state_transitions（状态转换表）
|
||
|
||
```sql
|
||
CREATE TABLE state_transitions (
|
||
id VARCHAR(36) PRIMARY KEY,
|
||
record_id VARCHAR(36) NOT NULL,
|
||
from_state VARCHAR(50) NOT NULL,
|
||
to_state VARCHAR(50) NOT NULL,
|
||
transition_data JSON,
|
||
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
||
FOREIGN KEY (record_id) REFERENCES onboarding_records(id),
|
||
INDEX idx_record_id (record_id)
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## API接口设计
|
||
|
||
### 1. 提交资产上链申请
|
||
|
||
```
|
||
POST /api/v1/assets/submit
|
||
Content-Type: application/json
|
||
Authorization: Bearer <token>
|
||
|
||
{
|
||
"asset_type": "real-estate",
|
||
"asset_info": {
|
||
"name": "商业地产A",
|
||
"location": "上海市浦东新区",
|
||
"area": 1000,
|
||
...
|
||
},
|
||
"legal_docs": [
|
||
{
|
||
"type": "legal_opinion",
|
||
"hash": "0x..."
|
||
}
|
||
],
|
||
"kyc_level": 2,
|
||
"jurisdiction": "CN"
|
||
}
|
||
|
||
Response:
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"asset_id": "uuid",
|
||
"state": "Pending"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 查询上链进度
|
||
|
||
```
|
||
GET /api/v1/assets/{asset_id}/status
|
||
Authorization: Bearer <token>
|
||
|
||
Response:
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"asset_id": "uuid",
|
||
"state": "ComplianceCheck",
|
||
"progress": 20,
|
||
"current_step": "AI合规审批中",
|
||
"estimated_time": "3分钟"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 获取资产详情
|
||
|
||
```
|
||
GET /api/v1/assets/{asset_id}
|
||
Authorization: Bearer <token>
|
||
|
||
Response:
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"asset_id": "uuid",
|
||
"state": "Listed",
|
||
"compliance_result": {...},
|
||
"valuation_result": {...},
|
||
"dna_result": {
|
||
"gnacs_code": "...",
|
||
"dna_hash": "0x...",
|
||
"code": "..."
|
||
},
|
||
"token_result": {
|
||
"contract_address": "0x...",
|
||
"token_symbol": "...",
|
||
"total_supply": "..."
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 下载链上权证
|
||
|
||
```
|
||
GET /api/v1/assets/{asset_id}/certificate
|
||
Authorization: Bearer <token>
|
||
|
||
Response: PDF文件
|
||
```
|
||
|
||
---
|
||
|
||
## 实施步骤
|
||
|
||
### 第1步: 创建项目结构（已完成）
|
||
|
||
### 第2步: 实现数据库模型
|
||
- `src/models/asset.rs`
|
||
- `src/models/onboarding_record.rs`
|
||
- `src/models/state_transition.rs`
|
||
|
||
### 第3步: 实现9个服务模块
|
||
- `src/services/orchestrator.rs` - 编排引擎
|
||
- `src/services/compliance.rs` - AI合规审批
|
||
- `src/services/valuation.rs` - AI估值
|
||
- `src/services/dna.rs` - DNA生成
|
||
- `src/services/constitution.rs` - 宪法执行引擎
|
||
- `src/services/custody.rs` - 托管对接
|
||
- `src/services/xtzh.rs` - XTZH铸造
|
||
- `src/services/token.rs` - 权益代币发行
|
||
- `src/services/listing.rs` - 链上公示
|
||
|
||
### 第4步: 实现API处理器
|
||
- `src/handlers/asset.rs` - 资产相关API
|
||
- `src/handlers/auth.rs` - 认证相关API
|
||
- `src/handlers/admin.rs` - 管理员相关API
|
||
|
||
### 第5步: 实现主程序
|
||
- `src/main.rs` - 启动服务器
|
||
|
||
### 第6步: 创建前端界面
|
||
- 使用React + TypeScript + Tailwind
|
||
- 用户前台 + 系统后台
|
||
|
||
### 第7步: 部署到备份服务器
|
||
- 配置域名和SSL
|
||
- 配置数据库
|
||
- 启动服务
|
||
|
||
---
|
||
|
||
## 质量保证
|
||
|
||
✅ **100%使用API调用** - 不重新实现底层功能
|
||
✅ **完整的错误处理** - 每个API调用都有错误处理
|
||
✅ **完整的日志记录** - 记录所有API调用和结果
|
||
✅ **完整的测试覆盖** - 单元测试 + 集成测试
|
||
✅ **完整的文档** - API文档 + 用户手册
|
||
|
||
---
|
||
|
||
**制定人**: NAC开发团队
|
||
**制定时间**: 2026-02-19
|
||
**文档状态**: 正式版
|