{
  "category": "architecture",
  "title": "NAC架构核心原则",
  "last_updated": "2026-02-07",
  "principles": [
    {
      "principle_id": "ARCH_001",
      "title": "四层架构体系",
      "description": "NAC采用L0-L1-L2-L3四层架构，每层职责明确",
      "layers": [
        {
          "layer": "L0",
          "name": "Base Layer",
          "chinese": "基础层",
          "responsibility": "基础数据结构、哈希算法（Blake3）、密码学原语",
          "key_components": [
            "Blake3 Hash",
            "Constitutional Layer（宪法层）",
            "Basic Data Structures"
          ]
        },
        {
          "layer": "L1",
          "name": "Protocol Layer",
          "chinese": "协议层",
          "responsibility": "核心协议实现：NVM、CBPP、ACC-20、Fragmentation",
          "key_components": [
            "NVM (NAC Virtual Machine)",
            "CBPP Consensus",
            "ACC-20 Protocol",
            "Fragmentation Protocol",
            "Advanced Architecture"
          ]
        },
        {
          "layer": "L2",
          "name": "Constitutional Layer",
          "chinese": "宪法层",
          "responsibility": "不可变的宪法规则，治理机制，合规验证",
          "key_components": [
            "Constitutional Rules",
            "Jurisdiction Management",
            "Asset Categories",
            "Governance System"
          ],
          "immutability": "L2是不可变层，只能通过严格的治理流程修改"
        },
        {
          "layer": "L3",
          "name": "Application Layer",
          "chinese": "应用层",
          "responsibility": "DApps、Charter合约、用户应用",
          "key_components": [
            "Charter Contracts",
            "DApps",
            "User Applications"
          ]
        }
      ],
      "must_do": [
        "严格遵守四层架构划分",
        "L2宪法层规则必须通过治理流程修改",
        "L1协议层实现必须符合L2宪法规则",
        "所有代码必须明确标注所属层级"
      ],
      "must_not_do": [
        "不要混淆层级职责",
        "不要绕过L2宪法层直接修改规则",
        "不要在L1实现L3的应用逻辑"
      ]
    },
    {
      "principle_id": "ARCH_002",
      "title": "OpCode命名规范",
      "description": "所有NVM OpCode必须使用UPPER_CASE命名",
      "rationale": "符合区块链行业标准（EVM使用UPPER_CASE），提高代码可读性",
      "examples": [
        "PUSH1（不是Push1）",
        "SSTORE（不是SStore）",
        "JUMP_DEST（不是JumpDest）",
        "CR_CREATE（不是CrCreate）"
      ],
      "must_do": [
        "所有OpCode使用UPPER_CASE",
        "多单词OpCode使用下划线分隔",
        "保持与EVM兼容的OpCode名称一致（如PUSH1, SSTORE）"
      ],
      "must_not_do": [
        "不要使用PascalCase（如Push1）",
        "不要使用camelCase（如push1）",
        "不要使用snake_case（如push_1）"
      ],
      "related_decisions": ["D001"]
    },
    {
      "principle_id": "ARCH_003",
      "title": "Blake3哈希统一",
      "description": "NAC使用Blake3作为唯一哈希算法，不使用SHA256或其他哈希",
      "rationale": "Blake3性能优异，安全性高，统一哈希算法简化实现",
      "must_do": [
        "所有哈希计算使用Blake3",
        "区块哈希使用Blake3",
        "交易哈希使用Blake3",
        "Merkle树使用Blake3"
      ],
      "must_not_do": [
        "不要使用SHA256",
        "不要使用Keccak256",
        "不要混用多种哈希算法"
      ]
    },
    {
      "principle_id": "ARCH_004",
      "title": "代码保留原则",
      "description": "永远不要删除代码，所有接口都是为未来功能预留",
      "rationale": "NAC是新开发的系统，很多接口和功能是为未来扩展预留的",
      "must_do": [
        "保留所有定义的接口和结构",
        "保留所有OpCode定义（即使暂未实现）",
        "保留所有模块和函数（即使暂未使用）"
      ],
      "must_not_do": [
        "不要删除'未使用'的代码",
        "不要使用#[allow(unused)]隐藏问题",
        "不要使用ignore/no_run隐藏测试问题"
      ],
      "correct_approach": [
        "遇到'未使用'警告时，添加proper imports",
        "遇到测试失败时，修复问题而非忽略",
        "遇到类型错误时，添加proper types"
      ]
    },
    {
      "principle_id": "ARCH_005",
      "title": "NAC原生设计原则",
      "description": "NAC不是任何公链的继承、衍生或扩展，必须使用NAC原生方法",
      "must_do": [
        "使用Rust的类型系统（enum, struct）",
        "使用强类型而非字符串表示",
        "使用NAC原生术语和概念",
        "使用NAC原生协议和算法"
      ],
      "must_not_do": [
        "不要使用JSON序列化（serde_json）表示复杂类型",
        "不要模仿以太坊的实现方式",
        "不要使用Cosmos的IBC协议",
        "不要使用比特币的UTXO模型"
      ],
      "common_mistakes": [
        {
          "mistake": "使用JSON字符串表示提案内容",
          "correction": "使用Rust enum定义强类型的ProposalContent",
          "example": "enum ProposalContent { CreateShard {...}, ModifyConfig {...} }"
        },
        {
          "mistake": "使用serde_json序列化",
          "correction": "使用Rust的类型系统和二进制序列化"
        }
      ]
    },
    {
      "principle_id": "ARCH_006",
      "title": "测试驱动开发",
      "description": "所有功能必须有完整的单元测试和集成测试",
      "must_do": [
        "每个模块必须有tests模块",
        "每个公开函数必须有测试用例",
        "测试必须覆盖正常流程和错误流程",
        "所有测试必须通过（cargo test）"
      ],
      "must_not_do": [
        "不要提交未通过测试的代码",
        "不要使用#[ignore]跳过测试",
        "不要使用no_run隐藏doctest问题"
      ],
      "test_requirements": [
        "单元测试覆盖率 > 80%",
        "所有公开API必须有doctest",
        "集成测试覆盖核心流程",
        "性能测试覆盖关键路径"
      ]
    }
  ]
}