# NAC统一定义模块（UDM）开发说明文档

**版本**: v0.1.0  
**作者**: Manus AI  
**日期**: 2025-02-07  
**状态**: 开发中

---

## 目录

1. [项目概述](#项目概述)
2. [架构设计](#架构设计)
3. [核心组件](#核心组件)
4. [已实现模块](#已实现模块)
5. [开发指南](#开发指南)
6. [测试指南](#测试指南)
7. [多语言支持](#多语言支持)
8. [路线图](#路线图)

---

## 项目概述

NAC统一定义模块（Unified Definition Module, UDM）是NAC原生公链的**单一真理来源（Single Source of Truth）**，统一管理整个NAC生态系统中的所有类型定义、函数签名、常量和版本信息。

### 设计哲学

**"定义即真理，规则即共识"**

UDM采用元定义系统（Meta-Definition System），实现了"定义如何定义"的自举机制，确保所有定义在整个NAC生态中保持一致性和可追溯性。

### 核心特性

- **语言无关**: 支持Rust、Go、Charter三种语言的自动绑定生成
- **版本管理**: 基于语义化版本（SemVer 2.0.0）的定义版本控制
- **分层架构**: 完全遵循NAC的3层架构（L2/L1/L0）
- **类型安全**: 强类型系统，编译时检查
- **可追溯性**: 每个定义都有唯一的UID和完整的元数据

### 技术栈

- **实现语言**: Rust 1.70+
- **序列化**: serde + serde_json
- **哈希算法**: SHA-256
- **测试框架**: Rust内置测试框架

---

## 架构设计

### 3层架构

NAC采用清晰的3层架构设计，UDM完全遵循这一架构：

```
┌─────────────────────────────────────────────────────────┐
│  L2: 宪法治理层 (Constitutional Governance Layer)      │
│  - 宪法收据、宪法条款、网络规则、CCRN授权              │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  L1: 多链协议层 (Multi-Chain Protocol Layer)           │
│  - CBPP共识、GNACS分类、ACC协议族、NVM虚拟机            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  L0: CSNP结构化网络层 (CSNP Structured Network Layer)  │
│  - GIDS、MA-RCM、AA-PE、FTAN、UCA                       │
└─────────────────────────────────────────────────────────┘
```

### 目录结构

```
nac-udm/
├── Cargo.toml                  # Rust项目配置
├── README.md                   # 项目说明
├── CHANGELOG.md                # 版本变更日志
├── DEVELOPMENT_GUIDE.md        # 本文档
├── API_SPECIFICATION.md        # API规范文档（待生成）
│
├── src/
│   ├── lib.rs                  # 模块入口
│   │
│   ├── registry/               # 核心注册表系统
│   │   ├── mod.rs
│   │   ├── uid.rs              # 统一标识符
│   │   ├── version.rs          # 版本管理
│   │   ├── definition.rs       # 定义抽象
│   │   ├── registry.rs         # 定义注册表
│   │   └── language.rs         # 多语言支持
│   │
│   ├── primitives/             # 基础原语类型
│   │   ├── mod.rs
│   │   ├── address.rs          # 地址类型（20字节）
│   │   ├── hash.rs             # 哈希类型（32字节）
│   │   ├── timestamp.rs        # 时间戳类型
│   │   └── signature.rs        # 签名类型
│   │
│   ├── l2_governance/          # L2: 宪法治理层
│   │   ├── mod.rs
│   │   ├── constitutional/     # 宪法收据、CEE
│   │   ├── clauses/            # 宪法条款库
│   │   ├── rules/              # 网络规则定义
│   │   ├── ccrn/               # 跨链中继节点授权
│   │   └── penalties/          # 惩罚条款
│   │
│   ├── l1_protocol/            # L1: 多链协议层
│   │   ├── mod.rs
│   │   ├── cbpp/               # 宪政区块生产协议
│   │   │   ├── mod.rs
│   │   │   ├── constitutional_receipt.rs
│   │   │   ├── fluid_block.rs
│   │   │   ├── open_production_network.rs
│   │   │   └── gossip_protocol.rs
│   │   ├── gnacs/              # 全球资产分类系统
│   │   │   ├── mod.rs
│   │   │   ├── code.rs
│   │   │   ├── category.rs
│   │   │   ├── jurisdiction.rs
│   │   │   ├── compliance.rs
│   │   │   └── risk.rs
│   │   ├── acc/                # ACC协议族（待实现）
│   │   └── nvm/                # NVM 2.0虚拟机（待实现）
│   │
│   ├── l0_native/              # L0: CSNP网络层
│   │   ├── mod.rs
│   │   ├── gids/               # 全域身份目录服务
│   │   ├── ma_rcm/             # 多链自适应连接管理器
│   │   ├── aa_pe/              # 资产感知传播引擎
│   │   ├── ftan/               # 碎片化交易聚合网络
│   │   └── uca/                # 统一跨链审计器
│   │
│   └── utils/                  # 工具函数
│       └── mod.rs
│
├── tests/                      # 集成测试
├── docs/                       # 文档
└── tools/                      # 工具脚本
```

---

## 核心组件

### 1. 统一标识符（UID）

UID是UDM的核心标识系统，为每个定义分配唯一的分层命名空间标识符。

**格式**: `nac.<layer>.<module>.<definition>`

**示例**:
- `nac.primitives.Address.v1` - 地址类型
- `nac.cbpp.ConstitutionalReceipt.v1` - 宪法收据
- `nac.gnacs.GNACSCode.v1` - GNACS编码

**特性**:
- 分层命名空间（Layer、Module、Definition）
- 父子关系查询
- 层级过滤
- 字符串解析和验证

### 2. 版本管理（Version）

基于语义化版本（SemVer 2.0.0）的版本管理系统。

**格式**: `major.minor.patch[-prerelease][+build]`

**示例**:
- `1.0.0` - 稳定版本
- `2.1.3` - 功能更新
- `3.0.0-alpha.1` - 预发布版本
- `1.2.3+20250207` - 带构建元数据

**特性**:
- 版本比较（>, <, ==）
- 兼容性检查
- 版本递增（bump_major, bump_minor, bump_patch）
- 预发布和构建元数据支持

### 3. 定义抽象（Definition）

元定义系统的核心，定义"什么是定义"。

**字段**:
- `uid`: UID - 唯一标识符
- `version`: Version - 版本号
- `name`: String - 定义名称
- `description`: String - 定义描述
- `definition_type`: DefinitionType - 定义类型
- `tags`: Vec<String> - 标签
- `deprecated`: bool - 是否弃用
- `dependencies`: Vec<UID> - 依赖关系
- `language_bindings`: HashMap<Language, LanguageBinding> - 多语言绑定

**定义类型**:
- `Type` - 类型定义（struct、enum）
- `Function` - 函数定义
- `Constant` - 常量定义
- `Protocol` - 协议定义
- `Module` - 模块定义

### 4. 定义注册表（DefinitionRegistry）

线程安全的定义管理系统。

**特性**:
- 多版本支持（同一定义可以有多个版本）
- 标签索引（快速按标签查询）
- 类型索引（快速按类型查询）
- 依赖追踪（查询定义的所有依赖）
- 线程安全（使用RwLock）

**API**:
```rust
// 注册定义
registry.register(definition)?;

// 查询定义
let def = registry.get(&uid)?;

// 按标签查询
let defs = registry.find_by_tag("cbpp");

// 按类型查询
let types = registry.find_by_type(DefinitionType::Type);

// 获取所有版本
let versions = registry.get_all_versions(&uid);
```

### 5. 多语言支持（Language）

支持Rust、Go、Charter三种语言的自动绑定生成。

**语言类型**:
- `Rust` - Rust语言
- `Go` - Go语言
- `Charter` - NAC智能合约语言

**语言绑定**:
```rust
pub struct LanguageBinding {
    pub language: Language,
    pub code: String,           // 生成的代码
    pub imports: Vec<String>,   // 导入依赖
    pub type_mappings: HashMap<String, String>, // 类型映射
}
```

**基础类型映射表**:

| NAC类型 | Rust | Go | Charter |
|---------|------|----|----|
| u8 | u8 | uint8 | u8 |
| u64 | u64 | uint64 | u64 |
| u128 | u128 | *big.Int | u128 |
| u256 | U256 | *big.Int | u256 |
| address | Address | [20]byte | address |
| hash | Hash | [32]byte | hash |
| bytes | Vec<u8> | []byte | bytes |
| string | String | string | string |

---

## 已实现模块

### 基础原语类型（Primitives）

#### Address（地址类型）

**UID**: `nac.primitives.Address.v1`

20字节地址类型，用于标识账户、合约等实体。

**字段**:
- `bytes: [u8; 20]` - 20字节数组

**方法**:
- `new(bytes: [u8; 20]) -> Self` - 创建新地址
- `from_slice(slice: &[u8]) -> Result<Self, String>` - 从切片创建
- `from_hex(hex: &str) -> Result<Self, String>` - 从十六进制字符串创建
- `as_bytes(&self) -> &[u8; 20]` - 获取字节数组
- `to_hex(&self) -> String` - 转换为十六进制字符串
- `zero() -> Self` - 零地址
- `is_zero(&self) -> bool` - 检查是否为零地址

**示例**:
```rust
use nac_udm::primitives::Address;

// 创建地址
let addr = Address::new([1u8; 20]);

// 从十六进制创建
let addr = Address::from_hex("0x1234567890abcdef1234567890abcdef12345678")?;

// 转换为十六进制
let hex = addr.to_hex();
```

#### Hash（哈希类型）

**UID**: `nac.primitives.Hash.v1`

32字节哈希类型，使用SHA-256算法。

**字段**:
- `bytes: [u8; 32]` - 32字节数组

**方法**:
- `new(bytes: [u8; 32]) -> Self` - 创建新哈希
- `from_slice(slice: &[u8]) -> Result<Self, String>` - 从切片创建
- `from_hex(hex: &str) -> Result<Self, String>` - 从十六进制字符串创建
- `sha256(data: &[u8]) -> Self` - 计算SHA-256哈希
- `as_bytes(&self) -> &[u8; 32]` - 获取字节数组
- `to_hex(&self) -> String` - 转换为十六进制字符串
- `zero() -> Self` - 零哈希
- `is_zero(&self) -> bool` - 检查是否为零哈希

**示例**:
```rust
use nac_udm::primitives::Hash;

// 计算哈希
let hash = Hash::sha256(b"hello world");

// 从十六进制创建
let hash = Hash::from_hex("a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e")?;
```

#### Timestamp（时间戳类型）

**UID**: `nac.primitives.Timestamp.v1`

Unix时间戳类型（秒级精度）。

**字段**:
- `secs: u64` - Unix时间戳（秒）

**方法**:
- `now() -> Self` - 当前时间
- `from_secs(secs: u64) -> Self` - 从秒数创建
- `as_secs(&self) -> u64` - 获取秒数
- `is_expired(&self, duration: u64) -> bool` - 检查是否过期
- `add_secs(&self, secs: u64) -> Self` - 增加秒数
- `sub_secs(&self, secs: u64) -> Self` - 减少秒数

**示例**:
```rust
use nac_udm::primitives::Timestamp;

// 当前时间
let now = Timestamp::now();

// 1小时后
let future = now.add_secs(3600);

// 检查是否过期
if now.is_expired(3600) {
    println!("已过期");
}
```

#### Signature（签名类型）

**UID**: `nac.primitives.Signature.v1`

数字签名类型（可变长度）。

**字段**:
- `bytes: Vec<u8>` - 签名字节

**方法**:
- `new(bytes: Vec<u8>) -> Self` - 创建新签名
- `from_slice(slice: &[u8]) -> Self` - 从切片创建
- `from_hex(hex: &str) -> Result<Self, String>` - 从十六进制字符串创建
- `as_bytes(&self) -> &[u8]` - 获取字节切片
- `to_hex(&self) -> String` - 转换为十六进制字符串
- `is_empty(&self) -> bool` - 检查是否为空
- `len(&self) -> usize` - 获取长度
- `empty() -> Self` - 空签名

### CBPP（宪政区块生产协议）

#### ConstitutionalReceipt（宪法收据）

**UID**: `nac.cbpp.ConstitutionalReceipt.v1`

宪法收据是CBPP的核心组件，任何试图改变链状态的操作必须先获得CR。

**字段**:
- `receipt_id: Hash` - 收据ID
- `transaction_hash: Hash` - 交易哈希
- `constitutional_hash: Hash` - 宪法哈希
- `execution_result_hash: Hash` - 执行结果哈希
- `timestamp: Timestamp` - 签发时间戳
- `validity_window: u64` - 有效期窗口（秒）
- `issuer_pubkey: Vec<u8>` - 签发者公钥（CEE实例）
- `signature: Signature` - 签名
- `validation_results: Vec<ValidationResult>` - 验证结果列表

**验证类型**:
- `KYC` - KYC验证
- `AML` - 反洗钱
- `AssetValuation` - 资产估值
- `ComplianceCheck` - 合规审查
- `JurisdictionCheck` - 司法辖区验证
- `ConstitutionalClause` - 宪法条款验证
- `SmartContractValidation` - 智能合约验证
- `Other(String)` - 其他

**方法**:
- `new(...) -> Self` - 创建新收据
- `add_validation_result(&mut self, result: ValidationResult)` - 添加验证结果
- `sign(&mut self, signature: Signature)` - 签名收据
- `verify(&self, current_time: Timestamp, valid_constitutional_hash: &Hash) -> bool` - 验证收据
- `is_expired(&self, current_time: Timestamp) -> bool` - 检查是否过期
- `get_weight(&self) -> u64` - 获取权重

**示例**:
```rust
use nac_udm::l1_protocol::cbpp::*;

// 创建宪法收据
let mut cr = ConstitutionalReceipt::new(
    tx_hash,
    const_hash,
    exec_hash,
    issuer_key,
    3600, // 1小时有效期
);

// 添加验证结果
cr.add_validation_result(ValidationResult::new(
    ValidationType::KYC,
    true,
    b"KYC passed",
));

// 签名
cr.sign(signature);

// 验证
if cr.verify(Timestamp::now(), &const_hash) {
    println!("收据有效");
}
```

#### FluidBlock（流体区块）

**UID**: `nac.cbpp.FluidBlock.v1`

流体区块使用三维坐标系统：(Epoch, Round, Branch)，支持DAG结构。

**字段**:
- `coordinates: BlockCoordinates` - 三维坐标
- `hash: Hash` - 区块哈希
- `parent_hashes: Vec<Hash>` - 父区块哈希列表
- `constitutional_hash: Hash` - 宪法哈希
- `timestamp: Timestamp` - 时间戳
- `transactions: Vec<TransactionWithReceipt>` - 交易列表
- `producer_pubkey: Vec<u8>` - 区块生产者公钥
- `signature: Signature` - 区块签名
- `size: u64` - 区块大小（字节）
- `weight: u64` - 区块权重

**三维坐标**:
- `epoch: u64` - 纪元
- `round: u64` - 轮次
- `branch: u32` - 分支

**方法**:
- `new(...) -> Self` - 创建新区块
- `sign(&mut self, signature: Signature)` - 签名区块
- `verify(&self, current_time: Timestamp, valid_constitutional_hash: &Hash) -> bool` - 验证区块
- `should_produce_block(last_block_time: Timestamp, pending_tx_count: usize, config: &BlockConfig) -> bool` - 检查是否应该出块

**示例**:
```rust
use nac_udm::l1_protocol::cbpp::*;

// 创建区块坐标
let coords = BlockCoordinates::new(1, 100, 0);

// 创建流体区块
let mut block = FluidBlock::new(
    coords,
    parent_hashes,
    const_hash,
    producer_key,
    transactions,
);

// 签名区块
block.sign(signature);

// 验证区块
if block.verify(Timestamp::now(), &const_hash) {
    println!("区块有效");
}
```

#### OpenProductionNetwork（开放生产网络）

**UID**: `nac.cbpp.OpenProductionNetwork.v1`

OPN管理区块生产者节点，任何满足条件的节点都可以加入。

**字段**:
- `producers: Vec<BlockProducer>` - 所有区块生产者
- `min_stake: u128` - 最低质押要求
- `min_reputation: f64` - 最低信誉要求

**区块生产者**:
- `pubkey: Vec<u8>` - 节点公钥
- `stake: u128` - 质押金额
- `reputation: f64` - 信誉分数
- `joined_at: Timestamp` - 加入时间
- `last_active: Timestamp` - 最后活跃时间
- `blocks_produced: u64` - 生产的区块数
- `blocks_validated: u64` - 验证的区块数

**方法**:
- `new(min_stake: u128, min_reputation: f64) -> Self` - 创建OPN
- `add_producer(&mut self, producer: BlockProducer) -> Result<(), String>` - 添加生产者
- `remove_producer(&mut self, pubkey: &[u8]) -> Result<(), String>` - 移除生产者
- `active_producer_count(&self, timeout_secs: u64) -> usize` - 获取活跃生产者数量

#### GossipProtocol（Gossip协议）

**UID**: `nac.cbpp.GossipProtocol.v1`

RVGP负责在网络中传播和验证宪法收据。

**消息类型**:
- `NewReceipt` - 新收据广播
- `ReceiptValidation` - 收据验证结果
- `NewBlock` - 区块广播
- `BlockValidation` - 区块验证结果

**方法**:
- `GossipMessage::new(...) -> Self` - 创建Gossip消息
- `verify(&self) -> bool` - 验证消息
- `GossipNode::new(pubkey: Vec<u8>) -> Self` - 创建Gossip节点
- `add_peer(&mut self, peer_pubkey: Vec<u8>)` - 添加对等节点
- `has_received(&self, message_hash: &Hash) -> bool` - 检查消息是否已接收
- `broadcast(&self, message: &GossipMessage) -> Vec<Vec<u8>>` - 广播消息

### GNACS（全球资产分类系统）

#### GNACSCode（48位编码）

**UID**: `nac.gnacs.GNACSCode.v1`

48位GNACS编码，为每个资产分配唯一的"数字基因"。

**编码结构**:
```
┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
│ 8 bits   │ 8 bits   │ 8 bits   │ 8 bits   │ 8 bits   │ 8 bits   │
│ Category │ SubCat   │ Juris    │ Comp     │ Risk     │ Checksum │
└──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘
```

**方法**:
- `new(...) -> Self` - 创建新编码
- `from_bytes(bytes: [u8; 6]) -> Result<Self, String>` - 从字节数组创建
- `from_hex(hex: &str) -> Result<Self, String>` - 从十六进制创建
- `to_hex(&self) -> String` - 转换为十六进制
- `category(&self) -> AssetCategory` - 获取资产大类
- `jurisdiction(&self) -> Jurisdiction` - 获取司法辖区
- `compliance_level(&self) -> ComplianceLevel` - 获取合规级别
- `risk_level(&self) -> RiskLevel` - 获取风险等级
- `verify_checksum(&self) -> bool` - 验证校验和
- `format_readable(&self) -> String` - 格式化为人类可读字符串

**示例**:
```rust
use nac_udm::l1_protocol::gnacs::*;

// 创建GNACS编码
let code = GNACSCode::new(
    AssetCategory::Equity,
    1,
    Jurisdiction::US,
    ComplianceLevel::High,
    RiskLevel::Medium,
);

// 转换为十六进制
let hex = code.to_hex();

// 格式化输出
println!("{}", code); // GNACS-0101-0102-0305
```

#### AssetCategory（资产分类）

**UID**: `nac.gnacs.AssetCategory.v1`

11种资产大类：

- `Equity` (0x01) - 股权资产
- `Debt` (0x02) - 债权资产
- `Physical` (0x03) - 实物资产
- `IntellectualProperty` (0x04) - 知识产权
- `Derivatives` (0x05) - 金融衍生品
- `Digital` (0x06) - 数字资产
- `Commodities` (0x07) - 大宗商品
- `RealEstate` (0x08) - 房地产
- `ArtCollectibles` (0x09) - 艺术品与收藏品
- `CarbonCredits` (0x0A) - 碳信用
- `Other` (0xFF) - 其他

**方法**:
- `from_u8(value: u8) -> Self` - 从u8转换
- `name(&self) -> &'static str` - 获取分类名称
- `description(&self) -> &'static str` - 获取分类描述
- `all() -> Vec<Self>` - 获取所有分类

#### Jurisdiction（司法辖区）

**UID**: `nac.gnacs.Jurisdiction.v1`

17个司法辖区：

- `US` (0x01) - 美国
- `CN` (0x02) - 中国
- `EU` (0x03) - 欧盟
- `UK` (0x04) - 英国
- `JP` (0x05) - 日本
- `SG` (0x06) - 新加坡
- `HK` (0x07) - 香港
- `CH` (0x08) - 瑞士
- `AE` (0x09) - 阿联酋
- `KY` (0x0A) - 开曼群岛
- `VG` (0x0B) - 英属维尔京群岛
- `LU` (0x0C) - 卢森堡
- `AU` (0x0D) - 澳大利亚
- `CA` (0x0E) - 加拿大
- `KR` (0x0F) - 韩国
- `Global` (0xFE) - 全球/跨境
- `Other` (0xFF) - 其他

**方法**:
- `from_u8(value: u8) -> Self` - 从u8转换
- `iso_code(&self) -> &'static str` - 获取ISO代码
- `full_name(&self) -> &'static str` - 获取全称
- `all() -> Vec<Self>` - 获取所有司法辖区

#### ComplianceLevel（合规级别）

**UID**: `nac.gnacs.ComplianceLevel.v1`

6个合规等级：

- `VeryHigh` (0x01) - 极高（100分）
- `High` (0x02) - 高（80分）
- `Medium` (0x03) - 中（60分）
- `Low` (0x04) - 低（40分）
- `VeryLow` (0x05) - 极低（20分）
- `Unknown` (0xFF) - 未知（0分）

**方法**:
- `from_u8(value: u8) -> Self` - 从u8转换
- `name(&self) -> &'static str` - 获取级别名称
- `description(&self) -> &'static str` - 获取级别描述
- `score(&self) -> u8` - 获取数值分数（0-100）

#### RiskLevel（风险等级）

**UID**: `nac.gnacs.RiskLevel.v1`

6个风险等级：

- `VeryLow` (0x01) - 极低（20分）
- `Low` (0x02) - 低（40分）
- `Medium` (0x03) - 中（60分）
- `High` (0x04) - 高（80分）
- `VeryHigh` (0x05) - 极高（100分）
- `Unknown` (0xFF) - 未知（0分）

**方法**:
- `from_u8(value: u8) -> Self` - 从u8转换
- `name(&self) -> &'static str` - 获取级别名称
- `description(&self) -> &'static str` - 获取级别描述
- `score(&self) -> u8` - 获取数值分数（0-100）

---

## 开发指南

### 环境准备

**系统要求**:
- Rust 1.70+ 
- Cargo
- Git

**安装Rust**:
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

### 编译项目

```bash
# 克隆项目
cd /home/ubuntu/nac-workspace/nac-udm

# 检查编译
cargo check

# 编译
cargo build

# 编译发布版本
cargo build --release
```

### 运行测试

```bash
# 运行所有测试
cargo test

# 运行特定模块的测试
cargo test primitives

# 运行特定测试
cargo test test_address_creation

# 显示测试输出
cargo test -- --nocapture
```

### 添加新定义

#### 步骤1: 创建定义文件

在相应的层级目录下创建新的定义文件，例如：

```rust
// src/l1_protocol/acc/acc20.rs

use crate::primitives::{Address, Hash};
use serde::{Deserialize, Serialize};

/// ACC-20 可替代代币标准
///
/// UID: nac.acc.ACC20.v1
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ACC20Token {
    /// 代币名称
    pub name: String,
    
    /// 代币符号
    pub symbol: String,
    
    /// 小数位数
    pub decimals: u8,
    
    /// 总供应量
    pub total_supply: u128,
    
    /// 合约地址
    pub contract_address: Address,
}

impl ACC20Token {
    /// 创建新的ACC-20代币
    pub fn new(name: String, symbol: String, decimals: u8, total_supply: u128) -> Self {
        Self {
            name,
            symbol,
            decimals,
            total_supply,
            contract_address: Address::zero(),
        }
    }
}
```

#### 步骤2: 更新模块导出

在`mod.rs`中导出新定义：

```rust
// src/l1_protocol/acc/mod.rs

pub mod acc20;

pub use acc20::*;
```

#### 步骤3: 添加测试

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_acc20_creation() {
        let token = ACC20Token::new(
            "Test Token".to_string(),
            "TEST".to_string(),
            18,
            1_000_000_000,
        );
        
        assert_eq!(token.name, "Test Token");
        assert_eq!(token.symbol, "TEST");
        assert_eq!(token.decimals, 18);
    }
}
```

#### 步骤4: 注册到UDM

```rust
use nac_udm::registry::*;

// 创建定义
let definition = Definition::builder()
    .uid(UID::parse("nac.acc.ACC20.v1")?)
    .version(Version::new(1, 0, 0))
    .name("ACC20Token")
    .description("ACC-20 fungible token standard")
    .definition_type(DefinitionType::Type)
    .add_tag("acc")
    .add_tag("token")
    .build();

// 注册到注册表
let registry = DefinitionRegistry::new();
registry.register(definition)?;
```

### 代码规范

**命名规范**:
- 类型名称：PascalCase（如`ConstitutionalReceipt`）
- 函数名称：snake_case（如`add_validation_result`）
- 常量名称：SCREAMING_SNAKE_CASE（如`MAX_BLOCK_SIZE`）
- 模块名称：snake_case（如`constitutional_receipt`）

**文档规范**:
- 所有公开类型和函数必须有文档注释
- 使用`///!`注释模块
- 使用`///`注释类型和函数
- 包含示例代码

**测试规范**:
- 每个公开函数至少一个测试
- 测试函数命名：`test_<function_name>_<scenario>`
- 使用`assert_eq!`、`assert!`等宏进行断言

---

## 测试指南

### 单元测试

每个模块都应该包含单元测试：

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_example() {
        // 测试代码
        assert_eq!(1 + 1, 2);
    }
}
```

### 集成测试

在`tests/`目录下创建集成测试：

```rust
// tests/integration_test.rs

use nac_udm::prelude::*;

#[test]
fn test_full_workflow() {
    // 完整的工作流测试
}
```

### 测试覆盖率

```bash
# 安装tarpaulin
cargo install cargo-tarpaulin

# 运行覆盖率测试
cargo tarpaulin --out Html
```

---

## 多语言支持

### Rust绑定

Rust是UDM的原生实现语言，直接使用即可：

```rust
use nac_udm::prelude::*;

let addr = Address::new([1u8; 20]);
```

### Go绑定（待实现）

计划使用代码生成工具自动生成Go绑定：

```go
package nac

type Address [20]byte

func NewAddress(bytes [20]byte) Address {
    return Address(bytes)
}
```

### Charter绑定（待实现）

计划为Charter智能合约语言生成绑定：

```charter
struct Address {
    bytes: [u8; 20]
}

impl Address {
    fn new(bytes: [u8; 20]) -> Self {
        Self { bytes }
    }
}
```

---

## 路线图

### 已完成（v0.1.0）

- ✅ 核心注册表系统（UID、Version、Definition、Registry、Language）
- ✅ 基础原语类型（Address、Hash、Timestamp、Signature）
- ✅ CBPP完整模块（ConstitutionalReceipt、FluidBlock、OPN、Gossip）
- ✅ GNACS完整模块（GNACSCode、AssetCategory、Jurisdiction、ComplianceLevel、RiskLevel）

### 进行中（v0.2.0）

- ⏳ ACC协议族（13个协议）
  - ACC-20（可替代代币）
  - ACC-721（不可替代代币）
  - ACC-1155（多代币标准）
  - ACC-RWA（RWA资产）
  - ACC-Compliance（合规）
  - ACC-Valuation（估值）
  - ACC-Custody（托管）
  - ACC-Collateral（抵押）
  - ACC-Redemption（赎回）
  - ACC-Insurance（保险）
  - ACC-Governance（治理）
  - ACC-XTZH（稳定币）
  - ACC-Reserve（储备）

- ⏳ NVM 2.0虚拟机
  - 225个基础操作码
  - 125个RWA专属指令
  - Gas计量模型

### 计划中（v0.3.0）

- ⏳ L2宪法治理层
  - 宪法条款库
  - 网络规则定义
  - CCRN授权管理
  - 惩罚条款

- ⏳ L0 CSNP网络层
  - GIDS（全域身份目录服务）
  - MA-RCM（多链自适应连接管理器）
  - AA-PE（资产感知传播引擎）
  - FTAN（碎片化交易聚合网络）
  - UCA（统一跨链审计器）

### 未来（v1.0.0）

- ⏳ 多语言绑定生成
  - Go绑定生成器
  - Charter绑定生成器
  - 类型映射优化

- ⏳ 工具链完善
  - 定义验证器
  - 定义迁移工具
  - 代码生成器

- ⏳ 文档完善
  - API规范文档
  - 使用示例
  - 最佳实践

---

## 附录

### 参考资料

- NAC原生公链完全去以太坊化架构设计
- CSNP V2.0技术白皮书
- 宪政区块生产协议（CBPP）技术白皮书
- 资产加密DNA管理系统技术白皮书

### 贡献指南

欢迎贡献代码、文档和测试！请遵循以下流程：

1. Fork项目
2. 创建特性分支（`git checkout -b feature/amazing-feature`）
3. 提交更改（`git commit -m 'Add amazing feature'`）
4. 推送到分支（`git push origin feature/amazing feature`）
5. 创建Pull Request

### 许可证

MIT License

---

**文档版本**: v0.1.0  
**最后更新**: 2025-02-07  
**维护者**: Manus AI