HedgeSync

HedgeSync 是一个面向商品套期保值分析的全栈项目，当前采用：

• 后端：FastAPI
• 前端：React + Vite + Ant Design
• Python 环境管理：uv
• 前端包管理：pnpm

项目用于完成商品现货与期货的对齐分析、套保比例测算、头寸换算、历史回测、压力测试、敏感性分析、基差预览和业务建议输出。

当前目录

HedgeSync/
├── backend/
│   ├── app/
│   │   ├── api/
│   │   ├── models/
│   │   ├── services/
│   │   └── main.py
│   └── tests/
├── frontend/
│   ├── public/
│   ├── src/
│   ├── package.json
│   ├── pnpm-lock.yaml
│   └── vite.config.ts
├── DESIGN.md
├── Dockerfile
├── pyproject.toml
├── uv.lock
├── run.py
├── start.sh
├── start.bat
└── sample_data.csv

核心功能

• 商品现货数据支持：
  • 上传 CSV
  • 在线拉取商品现货历史价格
• 期货数据支持：
  • AkShare 在线拉取
  • 上传 CSV
• 自动完成：
  • 日期识别
  • 缺失值处理
  • 重复日期去重
  • 期现货按日期对齐
• 套保分析支持：
  • 最小方差法
  • OLS 回归法
  • 相关系数调整法
• 自动输出：
  • 推荐套保比例
  • 理论手数与实际执行手数
  • 风险压降
  • 回测净盈亏
  • 波动率、最大回撤、Sharpe、Sortino、VaR、CVaR
  • 压力测试和敏感性分析
  • 基差预览和业务建议
  • Markdown 报告导出

页面模块

前端控制台目前包含以下工作区：

• 总览：指数走势、累计盈亏、滚动波动、风险雷达
• 预览：期现货基差快照、基差走势、期现货对齐明细
• 逻辑：套保比例、头寸、绩效核心指标、敏感性分析
• 压力：自动识别压力区间、压力摘要、常规区间对比
• 动作：业务建议和风险提示
• 导出：回测明细、敏感性结果、报告导出

数据来源说明

当前在线数据统一通过 AkShare 接入：

• 商品现货：商品现货历史/基差相关接口
• 期货历史：期货行情相关接口

说明：

• 商品现货在线输入使用商品品种代码，例如：RB、AL、CU、M
• 期货合约代码支持直接输入 RB、AL、CU 这类品种代码，后端会自动兼容主力连续口径
• 如果在线取数因非交易日、第三方源站限制或历史数据缺口出现异常，可以改用上传 CSV

启动环境

1. 初始化后端环境

uv sync --extra dev

2. 安装前端依赖

cd frontend
pnpm install

启动项目

Linux / macOS

./start.sh

Windows

start.bat

默认地址

• 后端：http://localhost:18000
• 前端：http://localhost:5173

说明：

• 启动脚本会检查 18000 和 5173 端口占用
• 若端口已被占用，会直接退出并提示先关闭旧进程
• 前端开发模式使用 --strictPort，不会自动跳到 5174

分别启动

后端

uv run --directory backend uvicorn app.main:app --app-dir . --host 0.0.0.0 --port 18000 --reload

前端

cd frontend
pnpm dev --host 0.0.0.0 --strictPort

后端接口

• GET /api/health
• POST /api/analysis/run

POST /api/analysis/run 当前主要支持的表单字段包括：

• spot_source
• spot_file
• spot_code
• future_source
• future_code
• future_file
• hedge_direction
• hedge_ratio_method
• spot_quantity
• future_contract_size
• window_size
• transaction_cost_rate
• price_change_threshold
• min_consecutive_days
• ratio_range
• sensitivity_steps
• custom_stress_start
• custom_stress_end
• use_rounded_contracts

计算与验证

项目当前已经对以下关键环节做了实现和校验：

• 套保比例计算
• 头寸换算
• 回测净盈亏与交易成本
• 风险压降口径统一
• 压力测试区间识别
• 敏感性分析真实头寸回测
• 最大回撤、VaR、CVaR、Sharpe、Sortino

后端测试命令：

uv run --extra dev pytest backend/tests

前端构建验证：

cd frontend
pnpm build

设计规范

界面设计规范参考：

• DESIGN.md

当前前端已经按该规范做了控制台化重构，并统一使用浅色卡片、浅色表格和暖色图表配色。

迁移说明

仓库已经从旧版脚本式结构迁移到当前全栈架构，旧的 Streamlit 页面和拆散的历史分析脚本已移除，默认仅维护：

• FastAPI 后端
• React + Ant Design 前端

注意事项

• 在线数据受第三方源站可用性影响
• 非交易日提示通常属于正常现象，不一定代表分析失败
• 商品现货与期货的单位、税口径、是否为企业内部成交价，需要在业务上自行保证一致
• 若需要更严谨的实盘复核，建议优先使用企业自有 CSV 数据