gavindiaz/chanlun.rs

Fork 0

Files

T

YuWuKunCheng 4bf9461009 规范文件

2026-06-07 14:34:05 +08:00

7.0 KiB

Raw Permalink Blame History

贡献指南

感谢你对 chanlun 项目的关注！

本项目将 Python 版缠论技术分析库 (chan.py) 完整移植为 Rust，同时通过 PyO3 绑定层保持 Python API 兼容。以下指南旨在帮助平滑贡献流程。

角色与分工

角色	范围	联系
维护者	架构决策、代码审查、发布	@YuWuKunCheng
贡献者	提交 PR、报告 Bug、改进文档	任何人

开发环境

必需工具

工具	最低版本	用途
Rust	1.85+	核心层编译
Python	3.10+	绑定层测试、对比验证
maturin	1.x	PyO3 绑定开发与安装

初始化

# 克隆仓库
git clone https://github.com/YuYuKunKun/chanlun.rs.git
cd chanlun.rs

# 核心层
cd chanlun
cargo build
cargo test

# 绑定层
cd ../chanlun-py
maturin develop
python3 -m pytest tests/test_all.py -v

# 确保 clippy 零警告
cd ../chanlun
cargo clippy

项目结构

chanlun.rs/
├── chan.py                          # Python 参考实现 (~4200 行)
├── chanlun/                         # Rust 核心层
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs                   # 模块注册
│       ├── config.rs                # 缠论配置 (62 字段, serde)
│       ├── types/                   # 基础类型
│       ├── kline/                   # K线层
│       ├── indicators/              # 技术指标
│       ├── algorithm/               # 核心算法 (笔/线段/中枢/背驰)
│       ├── structure/               # 结构体 (虚线/分型/特征)
│       ├── business/                # 业务层 (观察者/合成器/立体分析)
│       └── utils/                   # 工具
├── chanlun-py/                      # PyO3 Python 绑定
│   ├── Cargo.toml
│   ├── src/
│   │   ├── lib.rs                   # 模块注册与导出
│   │   ├── business_py.rs           # 业务层 Python 封装
│   │   ├── config_py.rs             # 配置 Python 封装
│   │   └── structure_py.rs          # 结构体 Python 封装
│   ├── chanlun/                     # Python 存根模块
│   │   └── __init__.py
│   └── tests/
│       └── test_all.py              # 完整测试套件
├── CLAUDE.md                        # AI 辅助开发指令
├── .github/                         # GitHub 模板
│   ├── pull_request_template.md
│   └── ISSUE_TEMPLATE/
│       ├── bug_report.md
│       ├── feature_request.md
│       └── custom.md
├── README.md
├── SECURITY.md
└── CODE_OF_CONDUCT.md

开发流程

从 Issue 开始

查找或创建相关 Issue
在 Issue 中讨论方案，达成共识后再开始编码
避免在没有 Issue 的情况下提交大型 PR

分支策略

# 从 develop 分支创建功能分支
git checkout develop
git pull origin develop
git checkout -b feature/your-feature-name

# 或从 develop 分支创建修复分支
git checkout -b fix/your-bug-fix

提交 PR

确保所有测试通过
确保 cargo clippy 零警告
推送到你的分支并发起 PR 到 develop
填写 PR 模板中的所有内容
等待审查并响应反馈

代码规范

中文标识符

所有类型名、方法名、字段名必须使用中文，与 chan.py 保持 1:1 对应：

// ✓ 正确
pub struct 缠论K线 { pub 高: SyncF64, pub 低: SyncF64 }
pub fn 方向(&self) -> 相对方向 { ... }

// ✗ 错误 — 不允许英文
pub struct ChanKline { pub high: f64 }

许可证头部

每个 .rs 文件必须以 MIT 许可证头部开始：

/*
 * MIT License
 *
 * Copyright (c) 2026 YuYuKunKun
 * ...
 */

代码风格

使用 cargo fmt 自动格式化
遵循 cargo clippy 建议（零警告）
仅写必要注释 — 解释"为什么"而非"做什么"
不对仅使用一次的代码做抽象
不添加方案之外的特性和错误处理

Rust 相关约定

#![allow(non_snake_case)] 和 #![allow(non_camel_case_types)] 已在 lib.rs 中声明
内部可变性优先用 AtomicI64/AtomicBool/SyncF64，复杂字段用 RwLock
Arc<分型> 通过 Arc::as_ptr 比较身份（而非值比较）
全局缓存使用 LazyLock<Mutex<>>，不使用 thread_local!
读写锁作用域化，防止死锁

测试指南

核心层测试

cd chanlun
cargo test             # 运行所有测试
cargo test -- <name>   # 运行匹配名称的测试

测试应覆盖：

类型构造/字段读写/Clone 后指针一致性
算法函数的边界情况（空序列、单元素、极端价格）
流式增量结果与静态重新分析的一致性
Send + Sync 编译期断言
跨线程读写不 panic

绑定层测试

cd chanlun-py
maturin develop
python3 -m pytest tests/test_all.py -v