# 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  
**文档状态**: 正式版