# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

RQSDK (Ricequant SDK) 是米筐量化平台的本地化开发工具包，提供命令行接口来管理和使用量化金融产品套件。这是一个 Python CLI 工具，使用 Click 框架构建。

**核心产品组件：**
- **rqdatac**: 金融数据 API（默认安装）
- **rqalpha_plus**: 多资产回测引擎
- **rqfactor**: 因子投研和检验工具
- **rqoptimizer**: 股票组合优化器
- **rqpattr**: 绩效归因计算

## 开发命令

### 安装开发依赖
```bash
pip install -r requirements_dev.txt
```

注意：开发依赖需要访问私有 PyPI 源 `https://rquser:Ricequant8@pypi2.ricequant.com/simple/`

### 运行测试
```bash
# 运行所有测试
python -m pytest tests

# 运行单个测试文件
python -m pytest tests/test_cli.py

# 运行特定测试类
python -m pytest tests/test_cli.py::TestUpdate

# 运行特定测试方法
python -m pytest tests/test_cli.py::TestUpdate::test_update_with_no_product
```

### 构建和安装
```bash
# 本地安装（开发模式）
pip install -e .

# 安装特定产品
pip install -e .[rqalpha_plus]
pip install -e .[rqfactor]
pip install -e .[rqoptimizer]

# 构建 wheel 包
python setup.py bdist_wheel
```

### 运行 CLI
```bash
# 直接运行
python -m rqsdk --help

# 或安装后使用
rqsdk --help
```

## 代码架构

### 入口点和命令结构
- **入口点**: `rqsdk/__init__.py:entry_point()` → `rqsdk/cmds.py:cli()`
- **CLI 框架**: 使用 Click 构建，所有命令定义在 `rqsdk/cmds.py`
- **命令注册**: 通过 `@cli.command()` 装饰器注册子命令

### 主要模块职责
- **cmds.py**: 所有 CLI 命令的实现（license, proxy, install, update, shell, version, update-data, check-data, download-data）
- **const.py**: 全局常量定义（产品列表、默认路径、PyPI 源地址、关注的包列表）
- **license_helper.py**: License 配置和验证逻辑
- **proxy_helper.py**: 代理配置验证
- **script_update.py**: pip 安装封装
- **_version.py**: 版本管理（使用 versioneer）

### 依赖管理架构
setup.py 中使用 `version_map` 字典定义产品依赖关系：
- 每个产品有独立的依赖集合
- 使用 Python 版本条件表达式（如 `python_version >= '3.7'`）
- 产品间依赖通过字典合并（`|` 操作符）继承
- rqalpha_plus 依赖 rqfactor，rqfactor 依赖 rqdatac

### 环境变量
- **RQSDK_LICENSE** / **RQDATAC_CONF**: License 配置（优先使用 RQSDK_LICENSE）
- **RQDATAC2_CONF**: 单独的 rqdatac 鉴权配置
- **RQSDK_PROXY** / **RQDATAC_PROXY** / **RQALPHA_PROXY**: 代理配置

### 第三方包构建
`scripts/build_third_party_packages/build.py` 提供自动化构建流程：
1. 解析 build_requirements.txt 安装构建依赖（支持 pip/conda，支持平台条件）
2. 下载源码包并解压
3. 构建 wheel 包（支持 setup.py 和 pyproject.toml）
4. 使用 auditwheel (Linux) 或 delocate (macOS) 修复依赖
5. 上传到私有 PyPI 服务器

## 测试说明

### 测试结构
- 使用 `unittest` 框架和 Click 的 `CliRunner` 进行测试
- 使用 `unittest.mock.Mock` 模拟 pip_install 等外部调用
- pytest.ini 配置忽略 UserWarning 和 RuntimeWarning

### 测试覆盖
- **test_cli.py**: CLI 命令测试（update, license, config, version, install）
- **test_demo.py**: 演示测试
- **test_mod_convertible.py**: 可转债模块测试
- **test_mod_option.py**: 期权模块测试

## CI/CD

### Jenkins Pipeline
- **分支**: master 和 develop 分支触发自动化测试
- **环境**: 使用 Docker 镜像 `ccr.ccs.tencentyun.com/ricequant/miniconda3-centos-builder:v1.0.8`
- **测试命令**: `python -m pytest tests`
- **通知**: 构建结果通过邮件发送给提交者

### 不同分支的 PyPI 源
- **master**: `https://rquser:Ricequant8@pypi2.ricequant.com/simple/`
- **develop**: `https://ricequant:RiceQuant77@pypi.ricequant.com:8080/simple/`

## 版本管理

使用 versioneer 进行版本管理：
- 版本号从 git tags 自动生成
- 不要手动修改 `_version.py`
- 使用 `rqsdk version` 查看所有相关包的版本

## 注意事项

1. **私有依赖**: 项目依赖私有 PyPI 源，需要正确的认证信息
2. **Python 版本兼容性**: 支持 Python 3.6.1 - 3.13，不同版本有不同的依赖约束
3. **平台差异**: 某些依赖（如 cryptography, numpy, pandas）在不同平台和 Python 版本有特定要求
4. **License 配置**: 大多数功能需要有效的 license 才能使用
5. **数据路径**: 默认 bundle 路径为 `~/.rqalpha-plus`
