概述

本文面向算法厂商侧开发，描述厂商接入 Xlight 算法母单能力时的接口、流程与状态约定。

参与方职责

参与方	核心职责	关键接口/回调
用户侧（User）	发起算法母单创建与操作	x1::XLTTradeApi::algo_create, x1::XLTTradeApi::algo_control
管理侧（Privilege）	账户管理、请求路由、状态分发	x1::XLTPrivilege::submit_algo_create_request, x1::XLTPrivilege::submit_algo_control_request, x1::XLTPrivilege::submit_algo_state
厂商侧（Vendor）	注册算法、处理请求、上报执行结果	x1::XLTTradeApi::vendor_algo_register, x1::XLTTradeApi::vendor_submit_algo_exec_report

厂商接入主流程

前置条件

算法厂商服务接入前，需先完成以下准备：

开通厂商账号：支持开通多个账号，建议每台服务实例使用一个独立账号（即 vendor_account_index）。
在 Xlight 柜台上架算法：上架成功后返回唯一算法类型标识 algo_type。
服务运行时账号登录后，需注册 algo_type（XLTTradeApi::vendor_algo_register），注册成功后才能接收对应算法母单请求。

运行期基础动作建议如下：

完成交易 API 初始化与登录（XLTTradeApi::initialize / XLTTradeApi::login）。
建议登录成功后立即订阅交易消息（XLTTradeApi::subscribe_trade_message），确保可接收算法相关推送。
按账号注册支持的算法类型（XLTTradeApi::vendor_algo_register）。

标准处理链路

步骤	厂商动作	对应接口/回调	说明
1	登录	x1::XLTTradeApi::login / x1::XLTTradeSpi::on_login	建立会话
2	订阅消息	x1::XLTTradeApi::subscribe_trade_message / x1::XLTTradeSpi::on_subscribe_trade_message	建议覆盖算法相关消息类型
3	注册算法类型	x1::XLTTradeApi::vendor_algo_register / x1::XLTTradeSpi::on_vendor_algo_register_response	注册后可接收对应母单请求
4	接收创建请求	x1::XLTTradeSpi::on_vendor_algo_create_request	管理侧转发母单创建请求
5	上报创建结果	x1::XLTTradeApi::vendor_submit_algo_exec_report	上报 `ALGO_EXEC_NEW` 或 `ALGO_EXEC_NEW_REJECT`
6	上报开始执行	x1::XLTTradeApi::vendor_submit_algo_exec_report	上报 `ALGO_EXEC_START`
7	按需申请交易令牌	x1::XLTTradeApi::vendor_auth_trade / x1::XLTTradeSpi::on_auth_trade	返回 `trade_token` 用于后续下单
8	执行交易并处理交易回报	x1::XLTTradeApi::insert_order / x1::XLTTradeApi::cancel_order / x1::XLTTradeSpi::on_order_response / x1::XLTTradeSpi::on_cancel_response / x1::XLTTradeSpi::on_trade_report / x1::XLTTradeSpi::on_order_error_response / x1::XLTTradeSpi::on_order_end	通过 `trade_token` 发起委托/撤单并处理回报：委托回报 `on_order_response`、撤单回报 `on_cancel_response`、成交回报 `on_trade_report`、委托错误回报 `on_order_error_response`、委托结束回报 `on_order_end`。上述回报中的 `xlt_msg_desc_t::account_index` 即母单 ID `xlt_algo_id`
9	持续上报执行状态	x1::XLTTradeApi::vendor_submit_algo_exec_report	例如 `ALGO_EXEC_FINISH` / `ALGO_EXEC_ABORT`
10	接收操作请求并回执	x1::XLTTradeSpi::on_vendor_algo_control_request + x1::XLTTradeApi::vendor_submit_algo_exec_report	上报 `ALGO_EXEC_CONTROL` 或 `ALGO_EXEC_CONTROL_REJECT`
11	接收管理侧状态通知	x1::XLTTradeSpi::on_vendor_algo_state	算法管理系统每次变更母单状态时通知厂商，厂商据此与本地状态机对账

关键时序图（厂商侧）

下图从厂商视角抽取了核心链路：登录/订阅/注册 -> 处理创建请求 -> 执行交易 -> 处理控制请求。

执行类型与状态建议映射

执行类型来自 AlgoExecType，建议状态映射来自 algo_v1_7.md。

ExecType	建议目标状态	说明
`ALGO_EXEC_NEW`	CREATED	母单创建成功
`ALGO_EXEC_NEW_REJECT`	REJECTED	母单创建被拒绝
`ALGO_EXEC_START`	STARTED	母单进入运行
`ALGO_EXEC_CONTROL`	CANCELED（按操作语义）	常见是撤单成功
`ALGO_EXEC_CONTROL_REJECT`	保持原状态	常见是撤单被拒
`ALGO_EXEC_FINISH`	FINISHED	母单正常完成
`ALGO_EXEC_ABORT`	ABORTED	母单异常中止

厂商侧重点回调

回调	场景	厂商处理建议
x1::XLTTradeSpi::on_vendor_algo_create_request	收到新母单创建请求	校验参数并尽快上报创建结果
x1::XLTTradeSpi::on_vendor_algo_control_request	收到母单操作请求（暂停/恢复/终止等）	幂等处理，明确成功/失败结果
x1::XLTTradeSpi::on_vendor_algo_state	算法管理系统状态通知（每次母单状态变动触发）	以管理平台状态为准更新本地状态：按 `xlt_algo_id` 迁移状态机；若与本地推导不一致则以回调为准并记录对账日志；对跳变/回退告警；落库状态变更时间与来源用于恢复追溯
x1::XLTTradeSpi::on_auth_trade	厂商授权响应	缓存 `trade_token` 并绑定会话
x1::XLTTradeSpi::on_order_response	委托确认	记录订单生命周期起点
x1::XLTTradeSpi::on_trade_report	成交回报	驱动算法执行进度与风控
x1::XLTTradeSpi::on_order_error_response	委托失败	及时上报 `ALGO_EXEC_ABORT` 或控制类失败

实践建议

以 xlt_algo_id 建立唯一上下文，保证创建/操作/状态上报串行有序。
对 on_vendor_algo_control_request 做幂等设计，避免重复操作导致状态抖动。
执行结果上报与交易回报处理解耦，避免回调阻塞导致断线。
对异常路径统一使用 ALGO_EXEC_ABORT，并附带可追踪的错误原因。
厂商重启恢复后，优先做状态对账，再恢复增量处理。