14 后端目录结构¶

目的¶

本章定义仓库中后端实现的组织方式。

核心要求¶

后端专有逻辑必须在结构上与 canonical core 分离。

分离规则¶

仓库必须明确区分 canonical 模块与 backend 模块。

canonical 模块负责协议语义、sidecar 工件、兼容导出、校验逻辑以及通用执行结果类型。
backend 模块负责目标相关的合法性检查、资源模型、调度策略、编译过程、执行入口与诊断输出。

backend 模块不得以不兼容的方式重新定义 canonical 语义对象。

当前仓库布局¶

在当前仓库中，后端专有代码位于 backends/，canonical 代码位于 src/qos_uqci/。活跃布局如下：

src/qos_uqci/
  ir.py
  ops.py
  devicespec.py
  calset.py
  result.py
  bundle.py
  driver.py
  openqasm_bridge.py
  errors.py

backends/
  base.py
  mock_superconducting/
    backend.py
    __init__.py
  mock_neutral_atom/
    backend.py
    __init__.py
  mock_ion_trap/
    README.md

这一布局与参考草案的建议结构保持同向，同时适配了当前仓库更轻量的 v0.1 组织方式。

当前后端组织¶

当前仓库包含：

backends/base.py，用于共享后端抽象或公共辅助逻辑
backends/mock_superconducting/，提供可运行的超导 mock backend
backends/mock_neutral_atom/，提供可运行的中性原子 mock backend
backends/mock_ion_trap/README.md，作为未来离子阱 mock backend 的预留扩展位

这一组织方式既保持了当前后端可运行，也清楚预留了未来平台家族的进入点。

与示例和测试的关系¶

后端目录结构还与仓库中的配套目录相互支撑：

examples/mock_backends/ 提供面向后端的 DeviceSpec 示例
tests/ 提供针对 runnable mock backend 的集成测试

这种分工使 backends/ 目录可以保持对实现代码本身的聚焦，而把演示工件与验证逻辑放入更适合的位置。

后端模块职责¶

每个后端包通常应在可发现的位置提供以下职责：

后端标识与能力摘要
面向该后端的 DeviceSpec 示例或工厂
对 canonical IR 的合法性检查
资源分配与调度逻辑
从 canonical 操作到 backend-native 步骤的编译逻辑
mock 或真实执行入口
诊断与调试摘要

这些职责可以集中在一个文件中实现，也可以随着复杂度增加拆分成多个模块。

在当前仓库中，为了保持 v0.1 的轻量性，可运行 mock backend 将大部分职责集中在较少文件中实现，以便于阅读与检查。

面向未来的后端家族¶

目录结构应为后续平台类型预留空间，例如：

离子阱
光子平台
自旋量子比特
模拟器或仿真器
云代理后端

顶层目录不应绑定厂商品牌。后端名称宜使用设备家族或稳定角色名，而不是临时营销名称。

打包考虑¶

后端既可以直接内置在仓库中，也可以作为可选外部包发布。规范性要求并不是物理上必须同仓，而是必须保持 canonical 边界清楚，并遵循标准驱动契约。

当前仓库将这些后端直接放在本地，是因为 v0.1 的定位是参考实现。未来版本即使将部分后端拆成可选包，也不应改变本章确立的架构边界。