Metadata-Version: 2.4
Name: futures-settlement-analysis
Version: 0.1.1
Summary: 期货结算单数据分析工具，支持CTP/监控中心/融航等多种格式
Project-URL: Repository, http://ifilevault.myasustor.com:3100/tridro/futures-settlement-analysis
Author-email: Tridro <tridro@beneorigin.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: orjson>=3.11.4
Requires-Dist: pandas>=2.3.3
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: xlrd>=2.0.2
Description-Content-Type: text/markdown

# futures-settlement-analysis

[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/futures-settlement-analysis)](https://pypi.org/project/futures-settlement-analysis/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)

期货结算单数据分析工具，支持 CTP / 中国期货监控中心 / 融航系统三种格式结算单，自动生成多维度交易统计报告。

## 功能特性

- **多格式支持**：CTP、中国期货监控中心(cfmmc)、融航系统(rohon) 三种结算单格式
- **多维度分析**：按合约、品种、买卖方向统计交易表现
- **期权行权支持**：自动识别行权/放弃，按开仓成本计算行权盈亏
- **净值曲线**：支持对数收益率(log)和百分比收益率(pct)两种模式
- **业绩归因**：年化收益率、最大回撤、夏普比率、索提诺比率、卡玛比率等
- **可视化报表**：Excel 报告含净值走势图、品种盈亏图、交易分布图、雷达图等
- **批量处理**：自动合并分析多个月份/年份的结算单文件

## 安装

### pip 安装（推荐）

```bash
pip install futures-settlement-analysis
```

安装后直接运行：

```bash
futures-analysis
```

### 源码安装

```bash
git clone http://ifilevault.myasustor.com:3100/tridro/futures-settlement-analysis.git
cd futures-settlement-analysis
git submodule update --init --recursive
pip install -e .
```

## 快速开始

### 1. 运行

首次运行会引导你完成配置：

```bash
futures-analysis
```

选择 `[1]` 使用当前目录下的 `data/` 子目录，将结算单文件复制进去即可。也可以直接通过命令行参数指定：

```bash
futures-analysis -s ./path/to/statements -o ./output
```

### 2. 查看报告

在输出目录下生成 `[资金账号]交易统计.xlsx`，用 Excel 或 WPS 打开。

## 命令行参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `-s, --source` | 结算单文件目录 | config.yaml 或交互输入 |
| `-o, --output` | 报告输出目录 | 当前工作目录 |
| `-t, --type` | 结算单类型: cfmmc / rohon / ctp | ctp |
| `-m, --method` | 收益率方法: log / pct | log |
| `-r, --risk-free` | 无风险利率 | 0.03 |

```bash
futures-analysis -s ./data -o ./output -t ctp -m log -r 0.03
```

## 配置文件

程序运行时在当前目录查找 `config.yaml`，模板参见 `config.example.yaml`：

```yaml
SOURCE_DIR: './data'
STATEMENT_TYPE: 'ctp'
OUTPUT_DIR: './output'
RISK_FREE_INTEREST_RATE: 0.03
STATISTIC_METHOD: 'log'
```

命令行参数优先级高于配置文件。

## 输出报告

| 工作表 | 内容 |
|--------|------|
| 账户净值 | 每日净值、份额、收益率 |
| 年度统计 | 年化收益、波动率、夏普、最大回撤等 |
| 账户统计 | 每日权益、保证金、风险度、出入金 |
| 成交明细 | 全部成交记录 |
| 平仓明细 | 全部平仓记录 |
| 行权明细 | 期权行权/放弃记录 |
| 交易分析(按合约) | 含行权盈亏列 |
| 交易分析(按品种) | 含行权盈亏列 |
| 交易分析(按买卖) | 含行权盈亏，手续费含行权费 |

**图表：**
- 净值走势图 · 权益+风险度双轴图 · 各品种交易分布饼图 · 品种盈亏柱状图 · 胜率/盈亏率雷达图 · 收益率分布直方图

## 统计指标

| 指标 | 说明 |
|------|------|
| 平仓盈亏 | 平仓交易利润总和 |
| 行权盈亏 | 期权行权/放弃按开仓成本计算的实际盈亏 |
| 净利润 | 平仓盈亏 + 行权盈亏 - 手续费(含行权费) |
| 交易成功率 | 盈利次数 / 总交易次数 |
| 交易盈亏率 | 盈利手数 / 总交易手数 |
| 年化收益率 | 折算至年度的收益率 |
| 最大回撤 | 历史最大净值回撤幅度 |
| 夏普比率 | 风险调整后收益，越高越好 |

## 项目结构

```
futures-settlement-analysis/
├── src/futures_analysis/
│   ├── __init__.py
│   ├── analysis.py       # 统计分析（含行权盈亏计算）
│   ├── loader.py         # 结算单加载与解析
│   ├── format.py         # Excel 输出与图表
│   └── data/             # 合约元数据（交易所/品种/乘数）
├── main.py               # 程序入口
├── config.example.yaml   # 配置文件模板
├── pyproject.toml        # 项目配置
└── docs/                 # 文档
```

## 常见问题

**Q: 支持哪些期货公司？**
> 输出格式符合 CTP、中国期货监控中心或融航系统标准即可。

**Q: 如何分析多个账户？**
> 分别创建不同的配置文件，修改 `SOURCE_DIR` 指向各账户的结算单目录。

**Q: 提示找不到文件？**
> 检查 `config.yaml` 中 `SOURCE_DIR` 路径是否正确，确认目录存在。

**Q: Excel 打不开？**
> 确认文件未被其他程序占用，推荐 Excel 2016+ 或 WPS 打开。

## 开发

```bash
git clone http://ifilevault.myasustor.com:3100/tridro/futures-settlement-analysis.git
cd futures-settlement-analysis
git submodule update --init --recursive
uv sync
uv run python -m pytest .tests/ -v
```

## 许可证

MIT License - 详见 [LICENSE](./LICENSE)

## 作者

Tridro - tridro@beneorigin.com
