接口文档

本文档由 backend/tests/export_api_inventory.py 从 FastAPI 运行时路由表自动生成， 共 88 个接口 / 71 个路径。代码改了重新跑一次脚本即可同步。

• 认证与账号 — 7 个接口 · 注册、登录、验证码、密码管理
• 用户中心 — 7 个接口 · 个人资料、Webhook 推送配置、券商配置
• 策略管理 — 8 个接口 · 策略 CRUD、复制、模板套用
• 回测执行 — 4 个接口 · 运行回测、查询报告、删除记录
• 行情监控 — 7 个接口 · 监控任务 CRUD、启停、立即执行、调度器状态
• 信号管理 — 5 个接口 · 信号查询、已读标记、失败重推
• 订单交易 — 5 个接口 · 模拟撮合下单、撤单、live 模式二次确认
• 行情数据 — 4 个接口 · K 线、快照、搜索、缓存统计
• 系统信息 — 1 个接口 · 平台版本与运行状态
• 管理后台 · 用户 — 6 个接口 · 用户 CRUD、封禁解锁、重置码
• 管理后台 · 系统 — 12 个接口 · 系统设置、角色权限、IP 黑名单、缓存
• 管理后台 · 日志与模板 — 13 个接口 · 操作日志、报错日志、策略模板
• 管理后台 · 全站资源 — 5 个接口 · 全站数据、全站监控、全站策略

一、通用约定

1.1 基础地址

生产环境（正式域名）：

https://quant.quasarxode.cn/api

本地开发：http://127.0.0.1:8000/api

1.2 认证方式

除公开接口外，所有接口都需要在请求头携带 Bearer Token：

Authorization: Bearer <access_token>

Token 由 POST /api/auth/login 或 POST /api/auth/register 获取， 有效期默认 720 分钟（可在系统设置中调整）。

1.3 响应格式

成功：直接返回业务数据，无统一外层包装。

{
  "id": 1,
  "name": "双均线策略",
  "status": "running"
}

失败：统一返回 detail 字段。

{ "detail": "权限不足，需要：strategy:write" }

参数校验失败（422）会额外带 errors 数组，字段已拍平：

{
  "detail": "请求参数校验失败",
  "errors": [
    { "field": "username", "message": "用户名需字母开头，仅含字母数字下划线，3-20 位" }
  ]
}

未捕获异常绝不回传堆栈（含文件路径等内部信息）， 只写入 error_logs 表与日志文件，客户端收到通用错误提示。

1.4 状态码约定

1.5 限流规则

滑动窗口，按 客户端 IP + 路由分组 计数。命中硬上限的路径用独立阈值：

触发限流返回 429，响应头带 Retry-After（秒）。

Nginx 反代时 X-Forwarded-For 用 $remote_addr 覆盖而非追加， 防止客户端伪造该头绕过限流。

1.6 权限点

细粒度 RBAC，权限码格式 域:动作。角色可自由组合，用户可拥有多个角色，权限取并集。 管理员角色拥有通配权限 *。

普通注册用户默认拥有全部 strategy / backtest / monitor / signal / order 共 11 个权限点。

二、接口详情

鉴权列含义：公开 = 无需登录；登录 = 需 Bearer Token； 权限 = 需特定权限码；管理员 = 需 admin 角色。

认证与账号

注册、登录、验证码、密码管理 · 7 个接口

GET /api/auth/captcha

获取图形验证码

• 鉴权：public — 无需登录
• 响应 200：CaptchaOut（函数返回类型注解）
• 返回字段：
• captcha_id（str，必填）
• image（str，必填）

POST /api/auth/login

用户登录

• 鉴权：public — 无需登录
• 请求体（LoginIn）：
• username（str，必填）
• password（str，必填）
• captcha_id（str，必填）
• captcha_code（str，必填）
• 响应 200：TokenOut（函数返回类型注解）
• 返回字段：
• access_token（str，必填）
• token_type（str，可选）
• expires_in（int，必填）
• user（UserOut，必填）

POST /api/auth/logout

退出登录

• 鉴权：auth — 登录用户
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

GET /api/auth/me

获取当前登录用户

• 鉴权：auth — 登录用户
• 响应 200：UserOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• username（str，必填）
• email（str，必填）
• nickname（str，可选）
• phone（str，可选）
• is_active（bool，可选）
• ban_reason（str，可选）
• webhook_url（str，可选）
• webhook_mode（str，可选）
• webhook_enabled（bool，可选）
• auto_trade_enabled（bool，可选）
• last_login_at（Optional，可选）
• created_at（Optional，可选）
• roles（list，可选）
• permissions（list，可选）

POST /api/auth/password/change

修改自己的密码

• 鉴权：auth — 登录用户
• 请求体（ChangePasswordIn）：
• old_password（str，必填）
• new_password（str，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

POST /api/auth/password/reset

用管理员发放的重置码改密

• 鉴权：public — 无需登录
• 请求体（ResetPasswordIn）：
• username（str，必填）
• token（str，必填）
• new_password（str，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

POST /api/auth/register

用户注册

• 鉴权：public — 无需登录
• 请求体（RegisterIn）：
• username（str，必填）
• email（str，必填）
• password（str，必填）
• captcha_id（str，必填）
• captcha_code（str，必填）
• 响应 200：TokenOut（函数返回类型注解）
• 返回字段：
• access_token（str，必填）
• token_type（str，可选）
• expires_in（int，必填）
• user（UserOut，必填）

用户中心

个人资料、Webhook 推送配置、券商配置 · 7 个接口

GET /api/users/broker

查看券商配置（密码不回显）

• 鉴权：auth — 登录用户
• 响应 200：dict（函数返回类型注解）

PUT /api/users/broker

配置券商账号（加密存储）

• 鉴权：auth — 登录用户
• 请求体（BrokerUpdateIn）：
• broker_account（str，可选，默认 ''）
• broker_password（str，可选，默认 ''）
• auto_trade_enabled（bool，可选，默认 False）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

GET /api/users/orders

我的订单列表

• 鉴权：auth — 登录用户
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• 响应 200：dict（函数返回类型注解）

GET /api/users/profile

获取个人资料

• 鉴权：auth — 登录用户
• 响应 200：UserOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• username（str，必填）
• email（str，必填）
• nickname（str，可选）
• phone（str，可选）
• is_active（bool，可选）
• ban_reason（str，可选）
• webhook_url（str，可选）
• webhook_mode（str，可选）
• webhook_enabled（bool，可选）
• auto_trade_enabled（bool，可选）
• last_login_at（Optional，可选）
• created_at（Optional，可选）
• roles（list，可选）
• permissions（list，可选）

PUT /api/users/profile

修改个人资料

• 鉴权：auth — 登录用户
• 请求体（ProfileUpdateIn）：
• nickname（Optional，可选，默认 None）
• phone（Optional，可选，默认 None）
• email（Optional，可选，默认 None）
• 响应 200：UserOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• username（str，必填）
• email（str，必填）
• nickname（str，可选）
• phone（str，可选）
• is_active（bool，可选）
• ban_reason（str，可选）
• webhook_url（str，可选）
• webhook_mode（str，可选）
• webhook_enabled（bool，可选）
• auto_trade_enabled（bool，可选）
• last_login_at（Optional，可选）
• created_at（Optional，可选）
• roles（list，可选）
• permissions（list，可选）

PUT /api/users/webhook

配置 QXBot 推送 Webhook

• 鉴权：auth — 登录用户
• 请求体（WebhookUpdateIn）：
• webhook_url（str，可选，默认 ''）
• webhook_mode（str，可选，默认 'xml'）
• webhook_enabled（bool，可选，默认 True）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

POST /api/users/webhook/test

测试 Webhook 连通性

• 鉴权：auth — 登录用户
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

策略管理

策略 CRUD、复制、模板套用 · 8 个接口

GET /api/strategies

我的策略列表

• 鉴权：perm — 查看策略
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query keyword（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

POST /api/strategies

创建策略

• 鉴权：perm — 创建/修改策略
• 请求体（StrategyIn）：
• name（str，必填）
• description（str，可选，默认 ''）
• mode（str，可选，默认 'both'）
• stock_pool（list，可选，默认 PydanticUndefined）
• start_date（str，可选，默认 '2020-01-01'）
• end_date（str，可选，默认 ''）
• initial_capital（float，可选，默认 100000）
• fast_ma（int，可选，默认 5）
• slow_ma（int，可选，默认 20）
• vol_window（int，可选，默认 20）
• vol_threshold（float，可选，默认 0.3）
• max_position_pct（float，可选，默认 0.2）
• max_drawdown_pct（float，可选，默认 0.2）
• max_consec_loss（int，可选，默认 3）
• pause_days（int，可选，默认 5）
• commission_rate（float，可选，默认 0.00025）
• min_commission（float，可选，默认 5.0）
• stamp_tax_rate（float，可选，默认 0.001）
• slippage_rate（float，可选，默认 0.0005）
• 响应 200：StrategyOut（函数返回类型注解）
• 返回字段：
• name（str，必填）
• description（str，可选）
• mode（str，可选）
• stock_pool（list，可选）
• start_date（str，可选）
• end_date（str，可选）
• initial_capital（float，可选）
• fast_ma（int，可选）
• slow_ma（int，可选）
• vol_window（int，可选）
• vol_threshold（float，可选）
• max_position_pct（float，可选）
• max_drawdown_pct（float，可选）
• max_consec_loss（int，可选）
• pause_days（int，可选）
• commission_rate（float，可选）
• min_commission（float，可选）
• stamp_tax_rate（float，可选）
• slippage_rate（float，可选）
• id（int，必填）
• owner_id（int，必填）
• created_at（Optional，可选）
• updated_at（Optional，可选）

GET /api/strategies/templates/list

可用策略模板

• 鉴权：perm — 查看策略
• 响应 200：list[TemplateOut]（函数返回类型注解）

POST /api/strategies/templates/{template_id}/apply

套用模板创建策略

• 鉴权：perm — 创建/修改策略
• 参数：
• path template_id（int，必填）
• query name（str，可选，默认 ``）
• 响应 200：StrategyOut（函数返回类型注解）
• 返回字段：
• name（str，必填）
• description（str，可选）
• mode（str，可选）
• stock_pool（list，可选）
• start_date（str，可选）
• end_date（str，可选）
• initial_capital（float，可选）
• fast_ma（int，可选）
• slow_ma（int，可选）
• vol_window（int，可选）
• vol_threshold（float，可选）
• max_position_pct（float，可选）
• max_drawdown_pct（float，可选）
• max_consec_loss（int，可选）
• pause_days（int，可选）
• commission_rate（float，可选）
• min_commission（float，可选）
• stamp_tax_rate（float，可选）
• slippage_rate（float，可选）
• id（int，必填）
• owner_id（int，必填）
• created_at（Optional，可选）
• updated_at（Optional，可选）

DELETE /api/strategies/{strategy_id}

删除策略

• 鉴权：perm — 删除策略
• 参数：
• path strategy_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

GET /api/strategies/{strategy_id}

策略详情

• 鉴权：perm — 查看策略
• 参数：
• path strategy_id（int，必填）
• 响应 200：StrategyOut（函数返回类型注解）
• 返回字段：
• name（str，必填）
• description（str，可选）
• mode（str，可选）
• stock_pool（list，可选）
• start_date（str，可选）
• end_date（str，可选）
• initial_capital（float，可选）
• fast_ma（int，可选）
• slow_ma（int，可选）
• vol_window（int，可选）
• vol_threshold（float，可选）
• max_position_pct（float，可选）
• max_drawdown_pct（float，可选）
• max_consec_loss（int，可选）
• pause_days（int，可选）
• commission_rate（float，可选）
• min_commission（float，可选）
• stamp_tax_rate（float，可选）
• slippage_rate（float，可选）
• id（int，必填）
• owner_id（int，必填）
• created_at（Optional，可选）
• updated_at（Optional，可选）

PUT /api/strategies/{strategy_id}

修改策略

• 鉴权：perm — 创建/修改策略
• 参数：
• path strategy_id（int，必填）
• 请求体（StrategyIn）：
• name（str，必填）
• description（str，可选，默认 ''）
• mode（str，可选，默认 'both'）
• stock_pool（list，可选，默认 PydanticUndefined）
• start_date（str，可选，默认 '2020-01-01'）
• end_date（str，可选，默认 ''）
• initial_capital（float，可选，默认 100000）
• fast_ma（int，可选，默认 5）
• slow_ma（int，可选，默认 20）
• vol_window（int，可选，默认 20）
• vol_threshold（float，可选，默认 0.3）
• max_position_pct（float，可选，默认 0.2）
• max_drawdown_pct（float，可选，默认 0.2）
• max_consec_loss（int，可选，默认 3）
• pause_days（int，可选，默认 5）
• commission_rate（float，可选，默认 0.00025）
• min_commission（float，可选，默认 5.0）
• stamp_tax_rate（float，可选，默认 0.001）
• slippage_rate（float，可选，默认 0.0005）
• 响应 200：StrategyOut（函数返回类型注解）
• 返回字段：
• name（str，必填）
• description（str，可选）
• mode（str，可选）
• stock_pool（list，可选）
• start_date（str，可选）
• end_date（str，可选）
• initial_capital（float，可选）
• fast_ma（int，可选）
• slow_ma（int，可选）
• vol_window（int，可选）
• vol_threshold（float，可选）
• max_position_pct（float，可选）
• max_drawdown_pct（float，可选）
• max_consec_loss（int，可选）
• pause_days（int，可选）
• commission_rate（float，可选）
• min_commission（float，可选）
• stamp_tax_rate（float，可选）
• slippage_rate（float，可选）
• id（int，必填）
• owner_id（int，必填）
• created_at（Optional，可选）
• updated_at（Optional，可选）

POST /api/strategies/{strategy_id}/copy

复制策略

• 鉴权：perm — 创建/修改策略
• 参数：
• path strategy_id（int，必填）
• 响应 200：StrategyOut（函数返回类型注解）
• 返回字段：
• name（str，必填）
• description（str，可选）
• mode（str，可选）
• stock_pool（list，可选）
• start_date（str，可选）
• end_date（str，可选）
• initial_capital（float，可选）
• fast_ma（int，可选）
• slow_ma（int，可选）
• vol_window（int，可选）
• vol_threshold（float，可选）
• max_position_pct（float，可选）
• max_drawdown_pct（float，可选）
• max_consec_loss（int，可选）
• pause_days（int，可选）
• commission_rate（float，可选）
• min_commission（float，可选）
• stamp_tax_rate（float，可选）
• slippage_rate（float，可选）
• id（int，必填）
• owner_id（int，必填）
• created_at（Optional，可选）
• updated_at（Optional，可选）

回测执行

运行回测、查询报告、删除记录 · 4 个接口

GET /api/backtests

我的回测记录

• 鉴权：perm — 查看回测
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query strategy_id（int | None，可选，默认 None）
• query status_filter（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

POST /api/backtests/run

运行回测

• 鉴权：perm — 运行回测
• 请求体（BacktestIn）：
• strategy_id（int，必填）
• ts_codes（Optional，可选，默认 None）
• start_date（Optional，可选，默认 None）
• end_date（Optional，可选，默认 None）
• 响应 200：BacktestOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• strategy_id（Optional，可选）
• strategy_name（str，必填）
• ts_codes（list，可选）
• start_date（str，必填）
• end_date（str，必填）
• initial_capital（float，必填）
• status（str，必填）
• error（str，可选）
• metrics（dict，可选）
• data_source（str，可选）
• duration_ms（int，可选）
• created_at（Optional，可选）

DELETE /api/backtests/{run_id}

删除回测记录

• 鉴权：perm — 查看回测
• 参数：
• path run_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

GET /api/backtests/{run_id}

回测详情（含曲线与交易明细）

• 鉴权：perm — 查看回测
• 参数：
• path run_id（int，必填）
• 响应 200：BacktestDetailOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• strategy_id（Optional，可选）
• strategy_name（str，必填）
• ts_codes（list，可选）
• start_date（str，必填）
• end_date（str，必填）
• initial_capital（float，必填）
• status（str，必填）
• error（str，可选）
• metrics（dict，可选）
• data_source（str，可选）
• duration_ms（int，可选）
• created_at（Optional，可选）
• result（dict，可选）
• params_snapshot（dict，可选）

行情监控

监控任务 CRUD、启停、立即执行、调度器状态 · 7 个接口

GET /api/monitors

我的监控任务

• 鉴权：perm — 查看监控
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• 响应 200：dict（函数返回类型注解）

POST /api/monitors

创建监控任务

• 鉴权：perm — 管理监控任务
• 请求体（MonitorIn）：
• strategy_id（int，必填）
• name（str，可选，默认 ''）
• interval_minutes（int，可选，默认 30）
• trading_time_only（bool，可选，默认 True）
• push_enabled（bool，可选，默认 True）
• 响应 200：MonitorOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• strategy_id（int，必填）
• name（str，必填）
• is_running（bool，必填）
• interval_minutes（int，必填）
• trading_time_only（bool，必填）
• push_enabled（bool，必填）
• last_run_at（Optional，可选）
• last_result（str，可选）
• run_count（int，可选）
• created_at（Optional，可选）

GET /api/monitors/scheduler/status

调度器运行状态

• 鉴权：perm — 查看监控
• 响应 200：dict（函数返回类型注解）

DELETE /api/monitors/{task_id}

删除监控任务

• 鉴权：perm — 管理监控任务
• 参数：
• path task_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

PUT /api/monitors/{task_id}

修改监控任务

• 鉴权：perm — 管理监控任务
• 参数：
• path task_id（int，必填）
• 请求体（MonitorIn）：
• strategy_id（int，必填）
• name（str，可选，默认 ''）
• interval_minutes（int，可选，默认 30）
• trading_time_only（bool，可选，默认 True）
• push_enabled（bool，可选，默认 True）
• 响应 200：MonitorOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• strategy_id（int，必填）
• name（str，必填）
• is_running（bool，必填）
• interval_minutes（int，必填）
• trading_time_only（bool，必填）
• push_enabled（bool，必填）
• last_run_at（Optional，可选）
• last_result（str，可选）
• run_count（int，可选）
• created_at（Optional，可选）

POST /api/monitors/{task_id}/run-now

立即执行一次扫描

• 鉴权：perm — 管理监控任务
• 参数：
• path task_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

POST /api/monitors/{task_id}/toggle

启动/停止监控

• 鉴权：perm — 管理监控任务
• 参数：
• path task_id（int，必填）
• 响应 200：MonitorOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• strategy_id（int，必填）
• name（str，必填）
• is_running（bool，必填）
• interval_minutes（int，必填）
• trading_time_only（bool，必填）
• push_enabled（bool，必填）
• last_run_at（Optional，可选）
• last_result（str，可选）
• run_count（int，可选）
• created_at（Optional，可选）

信号管理

信号查询、已读标记、失败重推 · 5 个接口

GET /api/signals

我的信号列表

• 鉴权：perm — 查看信号
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query side（str，可选，默认 ``）
• query ts_code（str，可选，默认 ``）
• query pushed（str，可选，默认 ``）
• query is_read（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

POST /api/signals/read-all

全部标记已读

• 鉴权：perm — 查看信号
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

GET /api/signals/stats

我的信号统计

• 鉴权：perm — 查看信号
• 响应 200：dict（函数返回类型注解）

POST /api/signals/{signal_id}/push

手动重推信号

• 鉴权：perm — 推送信号
• 参数：
• path signal_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

POST /api/signals/{signal_id}/read

标记已读

• 鉴权：perm — 查看信号
• 参数：
• path signal_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

订单交易

模拟撮合下单、撤单、live 模式二次确认 · 5 个接口

GET /api/orders

我的订单列表

• 鉴权：perm — 查看订单
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query status_filter（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

POST /api/orders

创建订单

• 鉴权：perm — 下单
• 请求体（OrderCreateIn）：
• ts_code（str，必填）
• side（str，必填）
• amount（Optional，可选，默认 None）
• volume（Optional，可选，默认 None）
• signal_id（Optional，可选，默认 None）
• mode（str，可选，默认 'paper'）
• 响应 200：OrderOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• ts_code（str，必填）
• stock_name（str，可选）
• side（str，必填）
• mode（str，必填）
• price（float，必填）
• volume（int，必填）
• amount（float，必填）
• fee（float，必填）
• status（str，必填）
• reject_reason（str，可选）
• created_at（Optional，可选）
• filled_at（Optional，可选）

GET /api/orders/capabilities

当前下单能力说明

• 鉴权：perm — 查看订单
• 响应 200：dict（函数返回类型注解）

POST /api/orders/{order_id}/cancel

撤单

• 鉴权：perm — 下单
• 参数：
• path order_id（int，必填）
• 响应 200：OrderOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• ts_code（str，必填）
• stock_name（str，可选）
• side（str，必填）
• mode（str，必填）
• price（float，必填）
• volume（int，必填）
• amount（float，必填）
• fee（float，必填）
• status（str，必填）
• reject_reason（str，可选）
• created_at（Optional，可选）
• filled_at（Optional，可选）

POST /api/orders/{order_id}/confirm

确认订单（live 模式二次确认）

• 鉴权：perm — 下单
• 参数：
• path order_id（int，必填）
• 响应 200：OrderOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• ts_code（str，必填）
• stock_name（str，可选）
• side（str，必填）
• mode（str，必填）
• price（float，必填）
• volume（int，必填）
• amount（float，必填）
• fee（float，必填）
• status（str，必填）
• reject_reason（str，可选）
• created_at（Optional，可选）
• filled_at（Optional，可选）

行情数据

K 线、快照、搜索、缓存统计 · 4 个接口

GET /api/market/cache/stats

行情缓存统计

• 鉴权：perm — 查看策略
• 响应 200：dict（函数返回类型注解）

GET /api/market/kline

日线 K 线数据

• 鉴权：perm — 查看策略
• 参数：
• query ts_code（str，必填） — 股票代码，如 000001.SZ
• query start（str，可选，默认 ``） — 开始日期 YYYY-MM-DD
• query end（str，可选，默认 ``） — 结束日期 YYYY-MM-DD
• 响应 200：dict（函数返回类型注解）

GET /api/market/quote

最新行情快照

• 鉴权：perm — 查看策略
• 参数：
• query ts_codes（str，必填） — 逗号分隔的股票代码
• 响应 200：dict（函数返回类型注解）

GET /api/market/search

股票搜索

• 鉴权：perm — 查看策略
• 参数：
• query keyword（str，可选，默认 ``）
• query limit（int，可选，默认 20）
• 响应 200：dict（函数返回类型注解）

系统信息

平台版本与运行状态 · 1 个接口

GET /api/system/info

系统信息（登录后可见）

• 鉴权：public — 无需登录
• 响应 200：dict（函数返回类型注解）

管理后台 · 用户

用户 CRUD、封禁解锁、重置码 · 6 个接口

GET /api/admin/users

用户列表

• 鉴权：admin — 管理员
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query keyword（str，可选，默认 ``）
• query is_active（str，可选，默认 ``）
• query role（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

POST /api/admin/users

新增用户

• 鉴权：admin — 管理员
• 请求体（AdminUserCreateIn）：
• username（str，必填）
• email（str，必填）
• password（str，必填）
• role_names（list，可选，默认 PydanticUndefined）
• 响应 200：UserOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• username（str，必填）
• email（str，必填）
• nickname（str，可选）
• phone（str，可选）
• is_active（bool，可选）
• ban_reason（str，可选）
• webhook_url（str，可选）
• webhook_mode（str，可选）
• webhook_enabled（bool，可选）
• auto_trade_enabled（bool，可选）
• last_login_at（Optional，可选）
• created_at（Optional，可选）
• roles（list，可选）
• permissions（list，可选）

DELETE /api/admin/users/{user_id}

删除用户

• 鉴权：admin — 管理员
• 参数：
• path user_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

PUT /api/admin/users/{user_id}

修改用户

• 鉴权：admin — 管理员
• 参数：
• path user_id（int，必填）
• 请求体（AdminUserUpdateIn）：
• email（Optional，可选，默认 None）
• nickname（Optional，可选，默认 None）
• is_active（Optional，可选，默认 None）
• ban_reason（Optional，可选，默认 None）
• role_names（Optional，可选，默认 None）
• 响应 200：UserOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• username（str，必填）
• email（str，必填）
• nickname（str，可选）
• phone（str，可选）
• is_active（bool，可选）
• ban_reason（str，可选）
• webhook_url（str，可选）
• webhook_mode（str，可选）
• webhook_enabled（bool，可选）
• auto_trade_enabled（bool，可选）
• last_login_at（Optional，可选）
• created_at（Optional，可选）
• roles（list，可选）
• permissions（list，可选）

POST /api/admin/users/{user_id}/reset-token

生成一次性密码重置码

• 鉴权：admin — 管理员
• 参数：
• path user_id（int，必填）
• 请求体（AdminResetPasswordIn）：
• new_password（Optional，可选，默认 None）
• 响应 200：dict（函数返回类型注解）

POST /api/admin/users/{user_id}/unlock

解锁账号

• 鉴权：admin — 管理员
• 参数：
• path user_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

管理后台 · 系统

系统设置、角色权限、IP 黑名单、缓存 · 12 个接口

POST /api/admin/cache/clear

清理缓存

• 鉴权：admin — 管理员
• 参数：
• query target（str，可选，默认 all）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

GET /api/admin/cache/stats

缓存统计

• 鉴权：admin — 管理员
• 响应 200：dict（函数返回类型注解）

GET /api/admin/ip-blacklist

IP 黑名单列表

• 鉴权：admin — 管理员
• 响应 200：list[dict]（函数返回类型注解）

POST /api/admin/ip-blacklist

添加 IP 黑名单

• 鉴权：admin — 管理员
• 请求体（IpBlacklistIn）：
• ip（str，必填）
• reason（str，可选，默认 ''）
• days（int，可选，默认 0）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

DELETE /api/admin/ip-blacklist/{item_id}

移除 IP 黑名单

• 鉴权：admin — 管理员
• 参数：
• path item_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

GET /api/admin/permissions

全部权限点

• 鉴权：admin — 管理员
• 响应 200：list[dict]（函数返回类型注解）

GET /api/admin/roles

全部角色

• 鉴权：admin — 管理员
• 响应 200：list[dict]（函数返回类型注解）

POST /api/admin/roles

新建角色

• 鉴权：admin — 管理员
• 请求体（RoleIn）：
• name（str，必填）
• description（str，可选，默认 ''）
• permission_codes（list，可选，默认 PydanticUndefined）
• 响应 200：dict（函数返回类型注解）

DELETE /api/admin/roles/{role_id}

删除角色

• 鉴权：admin — 管理员
• 参数：
• path role_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

PUT /api/admin/roles/{role_id}

修改角色权限

• 鉴权：admin — 管理员
• 参数：
• path role_id（int，必填）
• 请求体（RoleIn）：
• name（str，必填）
• description（str，可选，默认 ''）
• permission_codes（list，可选，默认 PydanticUndefined）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

GET /api/admin/settings

读取全部系统设置

• 鉴权：admin — 管理员
• 响应 200：dict（函数返回类型注解）

PUT /api/admin/settings

批量修改系统设置

• 鉴权：admin — 管理员
• 请求体（SettingsUpdateIn）：
• items（list，可选，默认 PydanticUndefined）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

管理后台 · 日志与模板

操作日志、报错日志、策略模板 · 13 个接口

GET /api/admin/data/backtests

全站回测记录

• 鉴权：admin — 管理员
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query username（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

GET /api/admin/data/orders

全站订单

• 鉴权：admin — 管理员
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query username（str，可选，默认 ``）
• query status_filter（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

GET /api/admin/data/signals

全站信号记录

• 鉴权：admin — 管理员
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query username（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

GET /api/admin/logs/audit

操作日志

• 鉴权：admin — 管理员
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query username（str，可选，默认 ``）
• query module（str，可选，默认 ``）
• query action（str，可选，默认 ``）
• query success（str，可选，默认 ``）
• query ip（str，可选，默认 ``）
• query start（str，可选，默认 ``）
• query end（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

GET /api/admin/logs/audit/export

导出操作日志 CSV

• 鉴权：admin — 管理员
• 参数：
• query username（str，可选，默认 ``）
• query module（str，可选，默认 ``）
• query action（str，可选，默认 ``）
• query success（str，可选，默认 ``）
• query ip（str，可选，默认 ``）
• query start（str，可选，默认 ``）
• query end（str，可选，默认 ``）
• 响应 200：StreamingResponse（函数返回类型注解）

GET /api/admin/logs/errors

报错日志

• 鉴权：admin — 管理员
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query keyword（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

POST /api/admin/logs/errors/clear

清空报错日志

• 鉴权：admin — 管理员
• 参数：
• query days（int，可选，默认 0） — 清理多少天前的，0=全部
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

DELETE /api/admin/logs/errors/{log_id}

删除单条报错日志

• 鉴权：admin — 管理员
• 参数：
• path log_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

GET /api/admin/overview

管理后台概览数据

• 鉴权：admin — 管理员
• 响应 200：dict（函数返回类型注解）

GET /api/admin/templates

全部策略模板（含未公开）

• 鉴权：admin — 管理员
• 响应 200：list[dict]（函数返回类型注解）

POST /api/admin/templates

新建模板

• 鉴权：admin — 管理员
• 请求体（TemplateIn）：
• name（str，必填）
• description（str，可选，默认 ''）
• params（dict，可选，默认 PydanticUndefined）
• is_public（bool，可选，默认 True）
• 响应 200：TemplateOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• name（str，必填）
• description（str，可选）
• params（dict，可选）
• is_public（bool，可选）
• created_at（Optional，可选）

DELETE /api/admin/templates/{template_id}

删除模板

• 鉴权：admin — 管理员
• 参数：
• path template_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

PUT /api/admin/templates/{template_id}

修改模板

• 鉴权：admin — 管理员
• 参数：
• path template_id（int，必填）
• 请求体（TemplateIn）：
• name（str，必填）
• description（str，可选，默认 ''）
• params（dict，可选，默认 PydanticUndefined）
• is_public（bool，可选，默认 True）
• 响应 200：TemplateOut（函数返回类型注解）
• 返回字段：
• id（int，必填）
• name（str，必填）
• description（str，可选）
• params（dict，可选）
• is_public（bool，可选）
• created_at（Optional，可选）

管理后台 · 全站资源

全站数据、全站监控、全站策略 · 5 个接口

GET /api/admin/monitors

全站监控任务

• 鉴权：admin — 管理员
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query username（str，可选，默认 ``）
• query status_filter（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

POST /api/admin/monitors/{task_id}/toggle

启停全站监控任务

• 鉴权：admin — 管理员
• 参数：
• path task_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

GET /api/admin/strategies

全站策略

• 鉴权：admin — 管理员
• 参数：
• query page（int，可选，默认 1）
• query page_size（int，可选，默认 20）
• query username（str，可选，默认 ``）
• query keyword（str，可选，默认 ``）
• query mode（str，可选，默认 ``）
• 响应 200：dict（函数返回类型注解）

POST /api/admin/strategies/{strategy_id}/disable

停用全站策略

• 鉴权：admin — 管理员
• 参数：
• path strategy_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

POST /api/admin/strategies/{strategy_id}/enable

恢复全站策略

• 鉴权：admin — 管理员
• 参数：
• path strategy_id（int，必填）
• 响应 200：MsgOut（函数返回类型注解）
• 返回字段：
• message（str，可选）

三、附录

3.1 在线交互式文档

服务内置 Swagger UI 与 OpenAPI 规范，仅在 DEBUG=true 时开启 （backend/app/main.py 里的 docs_url / openapi_url 条件）：

https://quant.quasarxode.cn/api/docs          # 仅 DEBUG 模式
https://quant.quasarxode.cn/api/openapi.json   # 仅 DEBUG 模式

生产环境默认关闭（避免把完整接口结构暴露给未授权访问者）。 需要临时开启时，在 .env 里设 DEBUG=true 并重启服务即可。 本文档本身包含了全部接口的说明，不依赖 Swagger。

3.2 核心数据模型

3.3 关键业务约束

3.4 错误码对照