# ituac-crypto-hub 开发约定

## 定位与边界

- 本仓库提供 ETH、后续 BTC 等链相关操作的 Python 能力库，不是交易所、交易策略或资产托管系统。
- 默认中文沟通和文档，英文代码标识；仅修改本仓库内与当前任务相关的文件。
- 开始前检查 `git status --short --branch`、HEAD（新仓库可能不存在）及相关差异。
  保留用户已有的工作树和暂存区内容，不自动提交、推送、重置、清理、部署或操作数据库。
- 仅讨论或只读请求不构成开发授权。新增依赖、框架和真实链操作应与明确需求匹配。

## 架构约束

- 使用 Python 3.11+、`src/core`、`src/eth` 同级包布局及 `pyproject.toml` 构建配置。
- `core` 仅容纳已被实际需求证明的公共原语；不能反向依赖币种包或链 SDK。
- `eth`、未来 `btc` 等包同级且互不依赖，各自拥有链模型、用例和适配器。
- 不把 ETH 的账户、nonce、gas 等概念强加给其他链；不提前实现万能基类、注册中心或空服务层。
- 外部节点、SDK、签名器接入时放入对应链的适配器，通过明确接口注入；导入包不得发起网络请求。
- 只导出稳定公共接口；新增能力、依赖、执行方式或边界时同步更新 README 和架构文档。

## 金额、资金与安全

- 链上金额用最小单位整数；人类可读金额只接受明确的十进制字符串或 `Decimal`。
  拒绝 `float`、非法数、负金额和不可精确表示的最小单位，不隐式四舍五入。
- 不手写密码学算法，不把通用地址格式检查描述成完整校验；代币精度不能套用 ETH 原生币精度。
- 不读取、打印、硬编码或提交真实私钥、助记词、RPC 凭据。忽略规则不能替代秘密审查。
- 网络和 chain ID 必须显式指定并核验，不默认连接主网；测试默认离线，集成测试明确选择加入。
- 签名、广播、授权合约、转账属于独立高风险操作，必须明确目标网络、账户、金额、费用及用户授权。
- 后续实现必须分离构建、签名、广播、回执和最终确认；广播超时是结果未知，不代表失败，不能盲目重试。
- 未支持或状态未知时明确报错，不能伪造余额、交易成功或确认状态。

## 代码与最小验证

- 公共函数需类型注解和契约说明；模块小而职责单一，异常类型明确，避免吞掉外部错误。
- 单元测试使用标准库 `unittest`，按币种组织；先覆盖实际行为、错误边界与金额精度，
  不为增加测试数量堆积相同断言。网络替身的结果不能被描述为真实链验证。
- 保留 `tests/__init__.py`，测试发现使用 `-t .`，避免 `tests/eth` 被当作顶层 `eth` 遮蔽源码包。
- 当前不安装依赖即可在根目录执行：

  ```sh
  PYTHONPATH=src python3 -m unittest discover -s tests -t . -v
  python3 -m compileall -q src tests
  git diff --check
  ```

- 修改打包配置时，在本地虚拟环境验证安装与包导入，不修改全局 Python 环境。
- 交付时检查新增文件和最终差异，说明已完成、实际验证、未验证范围；不把离线测试通过宣称为真实资金闭环。