Skip to content

API文档.md

Latest commit

 

History

History
420 lines (334 loc) · 7.6 KB

API文档.md

File metadata and controls

420 lines (334 loc) · 7.6 KB

SFRM API 文档

概述

SFRM (Spot and Futures Risk Management) 系统API提供完整的期现业务管理功能，包括项目管理、现货合同管理、期货结算单管理、自动计算分析等核心功能。

基础URL: http://localhost:8000/api

认证方式: Bearer Token (JWT)

认证

用户登录

POST /api/auth/login
Content-Type: application/x-www-form-urlencoded

username=admin&password=admin123

响应:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 604800
}

获取当前用户信息

GET /api/auth/me
Authorization: Bearer {token}

响应:

{
  "id": 1,
  "username": "admin",
  "email": "admin@sfrm.local",
  "full_name": "系统管理员",
  "role": "admin",
  "is_active": true,
  "created_at": "2024-01-01T00:00:00",
  "updated_at": "2024-01-01T00:00:00"
}

项目管理

获取项目列表

GET /api/projects?page=1&size=20&status=in_progress&project_type=hedge&search=螺纹钢
Authorization: Bearer {token}

查询参数:

  • page: 页码 (默认: 1)
  • size: 每页数量 (默认: 20)
  • status: 项目状态筛选
  • project_type: 项目类型筛选
  • search: 搜索关键词

响应:

{
  "items": [
    {
      "id": 1,
      "name": "螺纹钢库存对冲项目",
      "code": "T20240001",
      "project_type": "hedge",
      "hedge_subtype": "inventory_hedge",
      "status": "in_progress",
      "total_pnl": 15000.00,
      "hedge_ratio": 0.95,
      "risk_exposure": 25000.00,
      "spot_contracts_count": 2,
      "futures_settlements_count": 3,
      "created_at": "2024-01-01T00:00:00"
    }
  ],
  "total": 1,
  "page": 1,
  "size": 20,
  "pages": 1
}

创建项目

POST /api/projects
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "螺纹钢库存对冲项目",
  "project_type": "hedge",
  "hedge_subtype": "inventory_hedge",
  "related_symbols": ["RB", "I"],
  "initial_capital": 100000.00,
  "description": "对冲螺纹钢库存价格下跌风险"
}

更新项目

PUT /api/projects/{project_id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "更新后的项目名称",
  "status": "archived"
}

删除项目

DELETE /api/projects/{project_id}
Authorization: Bearer {token}

关联合同到项目

POST /api/projects/{project_id}/contracts
Authorization: Bearer {token}
Content-Type: application/json

{
  "project_id": 1,
  "contract_id": 1
}

现货合同管理

获取合同列表

GET /api/spot-contracts?page=1&size=20&status=completed&commodity_name=螺纹钢
Authorization: Bearer {token}

创建合同

POST /api/spot-contracts
Authorization: Bearer {token}
Content-Type: application/json

{
  "contract_number": "SC20240001",
  "counterparty": "钢铁贸易公司A",
  "sign_date": "2024-01-01T00:00:00",
  "commodity_name": "螺纹钢",
  "specification": "HRB400 16mm",
  "unit": "吨",
  "total_quantity": 1000.00,
  "unit_price": 4000.00,
  "total_amount": 4000000.00,
  "tax_type": "inclusive",
  "settlement_method": "monthly"
}

批量导入合同

POST /api/spot-contracts/import
Authorization: Bearer {token}
Content-Type: multipart/form-data

file: [Excel文件]

Excel模板格式:

合同编号 交易对手 签订日期 标的名称 规格 单位 总数量 单价 含税/不含税 结算方式

创建交付记录

POST /api/spot-contracts/{contract_id}/deliveries
Authorization: Bearer {token}
Content-Type: application/json

{
  "delivery_date": "2024-01-15T00:00:00",
  "quantity": 500.00,
  "warehouse": "上海仓库",
  "delivery_type": "in",
  "notes": "第一批入库"
}

期货结算单管理

获取结算单列表

GET /api/futures-settlements?page=1&size=20&symbol=RB&direction=long
Authorization: Bearer {token}

创建结算单

POST /api/futures-settlements
Authorization: Bearer {token}
Content-Type: application/json

{
  "contract_code": "RB2405.SHF",
  "symbol": "RB",
  "commodity_name": "螺纹钢",
  "expiry_date": "2024-05-15T00:00:00",
  "transaction_type": "open",
  "direction": "short",
  "lots": 100,
  "open_price": 3950.00,
  "trade_date": "2024-01-01T00:00:00",
  "commission": 50.00
}

更新结算价格

POST /api/futures-settlements/{settlement_id}/update-settlement-price
Authorization: Bearer {token}
Content-Type: application/json

{
  "settlement_price": 3980.00
}

获取头寸汇总

GET /api/futures-settlements/positions/summary?symbol=RB
Authorization: Bearer {token}

获取到期预警

GET /api/futures-settlements/expiry-warnings?days=15
Authorization: Bearer {token}

分析计算

计算项目指标

POST /api/analytics/projects/{project_id}/calculate
Authorization: Bearer {token}
Content-Type: application/json

{
  "calculation_date": "2024-01-15T00:00:00"
}

响应:

{
  "project_id": 1,
  "calculation_date": "2024-01-15T00:00:00",
  "spot_pnl": 25000.00,
  "futures_pnl": -10000.00,
  "total_pnl": 15000.00,
  "hedge_ratio": 0.95,
  "risk_exposure": 25000.00,
  "spot_position": 1000.00,
  "futures_position": -950.00,
  "spread_return": null
}

获取仪表盘统计

GET /api/analytics/dashboard/stats
Authorization: Bearer {token}

响应:

{
  "total_projects": 5,
  "active_projects": 3,
  "total_pnl": 150000.00,
  "top_projects": [
    {
      "id": 1,
      "name": "螺纹钢库存对冲项目",
      "code": "T20240001",
      "total_pnl": 50000.00,
      "status": "in_progress"
    }
  ],
  "risk_warnings": [
    {
      "project_id": 2,
      "project_name": "铁矿石套利项目",
      "warnings": ["对冲率异常: 0.75"]
    }
  ]
}

获取盈亏趋势

GET /api/analytics/projects/{project_id}/profit-loss-trend?days=30
Authorization: Bearer {token}

获取头寸平衡

GET /api/analytics/projects/{project_id}/position-balance?days=30
Authorization: Bearer {token}

运行压力测试

POST /api/analytics/projects/{project_id}/stress-test
Authorization: Bearer {token}
Content-Type: application/json

[
  {
    "name": "价格上涨10%",
    "price_change_percent": 0.10,
    "duration_days": 1,
    "description": "标的价格单日上涨10%"
  }
]

错误响应格式

所有API错误响应遵循统一格式：

{
  "detail": "错误描述信息"
}

常见HTTP状态码：

  • 200: 成功
  • 201: 创建成功
  • 400: 请求参数错误
  • 401: 未认证
  • 403: 权限不足
  • 404: 资源不存在
  • 422: 表单验证失败
  • 500: 服务器内部错误

数据字典

项目状态

  • in_progress: 进行中
  • archived: 已归档
  • paused: 暂停

项目类型

  • hedge: 套保
  • arbitrage: 套利

套保子类型

  • inventory_hedge: 库存对冲
  • purchase_hedge: 采购对冲

合同状态

  • not_fulfilled: 未履约
  • partially_fulfilled: 部分履约
  • completed: 已完成

交易类型

  • open: 开仓
  • close: 平仓

方向

  • long: 多头
  • short: 空头

税率类型

  • inclusive: 含税
  • exclusive: 不含税

结算方式

  • cash_on_delivery: 款到发货
  • monthly: 月结
  • other: 其他

用户角色

  • admin: 管理员
  • operator: 操作员

在线文档

启动后端服务后，可以通过以下地址访问交互式API文档：