# 项目架构

## 1. 背景与本次决策

目标是沉淀可复用的虚拟货币操作解决方案，从 ETH 开始，逐步加入 BTC 等链。
现有仓库只有 Python IDE 示例，故延续 Python，采用单仓库、单分发包、链能力模块化布局。
`src` 仅作为源码目录，直接包含同级 `core`、`eth` 包，不再增加项目名命名空间。
分发包名称仍为 `ituac-crypto-hub`，导入使用 `from eth import ...` / `from core import ...`。
顶层包名较通用，使用项目独立虚拟环境；未来引入 SDK 时检查是否与 `eth`、`core` 同名冲突。
本次状态：基础骨架已落地；下文节点、钱包和交易能力均为后续方向，不代表已经实现。

备选方案及取舍：

- 暂不引入 FastAPI / 微服务：尚无 HTTP、认证或部署需求，先让能力能被脚本和未来服务复用。
- 暂不为每条链建立独立仓库或分发包：降低早期维护成本；需独立发布或出现依赖冲突时再拆分。
- 不建立统一交易大接口：仅有 ETH 首期需求，提前抽象容易把链特有语义泄漏到公共层。
- 暂不安装链 SDK：首期只有离线基础能力；节点接入时再按官方维护状态、接口和测试支持选型。

## 2. 依赖方向

```text
调用方（脚本 / 未来 API / 任务）
        ↓             ↓
       eth        btc（未来）
        ↓             ↓
              core
```

`core` 不导入任何币种包；币种包互不导入。当前 `eth.units` 依赖 `core.errors`，
`eth.__init__` 暴露经过测试的金额转换接口。

每条链在真实需求出现时再增长为：

```text
eth/
  units.py              # 已有：原生币单位转换
  models.py             # 未来：本链请求、结果和值对象
  ports.py              # 未来：节点与签名器接口，按能力拆分
  services/             # 未来：查询、交易等用例，不绑定 SDK
  adapters/             # 未来：RPC / SDK / 外部签名器实现
```

以上未来文件不预建空壳。外部适配器实现端口，调用入口负责组装和注入；用例不直接实例化 SDK。
单元测试注入离线替身；集成测试独立配置网络及节点，不在包导入时建立连接。

## 3. 公共层与链专属层

| 归属 | 内容 |
| --- | --- |
| `core` | 当前公共异常；未来有真实复用证据的原语 |
| `eth` | 原生 ETH 单位、后续地址 / chain ID / 费用 / 交易与回执语义 |
| 未来 `btc` | BTC 自有单位、网络 / 地址 / UTXO / 手续费 / 交易模型 |
| 调用应用 | 身份权限、业务订单、持久化、调度、审计和部署，当前不实现 |

链与资产分开：原生 ETH 的单位转换不能用于未知精度的代币。
ERC-20 若进入范围，先归于 ETH / EVM 相关能力，不因币种名称拆成重复的链客户端。
其他 EVM 链及共享 `evm` 层只有在需求明确、复用证据充分后再决定。

## 4. 后续操作的安全契约

- 节点 URL、目标网络、预期链标识显式配置，并核验节点身份；不得隐式落到主网。
- 金额边界使用最小单位整数，展示才转换 Decimal；拒绝浮点和静默精度损失。
- 密钥通过专门签名接口管理，不进入普通配置对象、日志、测试夹具或异常输出；不自行实现密码学。
- 交易构建、费用估算、签名、广播、回执查询及最终确认分离。返回交易哈希不等于成功。
- 对外错误需区分输入错误、节点拒绝、传输故障、响应格式错误、执行失败和结果未知。
- 广播超时不自动重发资金操作；引入写能力前明确幂等、并发、费用上限、重试和链重组策略。
- 真实转账或合约授权必须另行明确授权；离线测试不构成资金操作许可。

## 5. 增加 BTC 等链

1. 明确该链首批用例与非目标，验证协议和 SDK 官方资料。
2. 新建 `src/btc/`，独立维护公共接口和链特有模型，不从 `eth` 继承。
3. 新建 `tests/btc/`，验证单位、边界、失败路径；有节点适配器后再提供可选集成测试。
4. SDK 依赖优先用按链可选依赖声明，防止 ETH 用户被迫安装 BTC 全部依赖。
5. 只有已经出现的共同需求才提取到 `core`，同时更新此文档和 README。

## 6. 建议演进顺序（待具体需求确认）

1. ETH 只读接入：节点身份、区块、原生币余额、交易及回执查询。
2. ETH 写能力：构建和估算 → 独立签名器 → 显式广播 → 确认跟踪及异常恢复。
3. 按需求扩展代币、事件查询等能力。
4. BTC 首期只读能力，再按其自身模型补充资金操作。

验收分开记录源码 / 离线测试 / 本地链或测试网 / 真实节点 / 真实资金证据。
目前只提供并验证基础库；不声明主网、RPC 或真实交易已验证。