kaq-quant-common 0.2.12__py3-none-any.whl

kaq_quant_common/api/common/__init__.py

@@ -0,0 +1 @@
+

kaq_quant_common/api/common/api_interface.py

@@ -0,0 +1,38 @@
+from abc import ABC
+from functools import wraps
+from typing import Callable, Type
+
+from pydantic import BaseModel
+
+
+def api_method(request_model: Type[BaseModel], response_model: Type[BaseModel]):
+    """
+    api 方法注解
+    :param request_model: 请求模型
+    :param response_model: 响应模型
+    :return:
+    """
+
+    def decorator(func: Callable):
+        # 将注解信息绑定到原始函数
+        func._is_api_method = True
+        func._request_model = request_model
+        func._response_model = response_model
+
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        # 同步注解信息到包装函数，便于通过inspect发现
+        wrapper._is_api_method = True
+        wrapper._request_model = request_model
+        wrapper._response_model = response_model
+
+        return wrapper
+
+    return decorator
+
+
+# 定义 api 接口，暂时没啥用
+class ApiInterface(ABC):
+    pass

kaq_quant_common/api/common/auth.py

@@ -0,0 +1,118 @@
+import os
+from typing import Any, Optional, Tuple
+
+from kaq_quant_common.utils import yml_utils
+
+# 统一的简单鉴权：基于一个共享的 token
+# - 来源优先级：环境变量 KAQ_API_TOKEN > 配置文件 kaq.api_token
+# - 如果未配置 token，则认为鉴权关闭（通过）
+
+
+def _get_expected_token(pkg_name: Optional[str] = None) -> Optional[str]:
+    # 环境变量优先
+    token = os.getenv("KAQ_API_TOKEN")
+    if token:
+        return token.strip()
+    # 配置文件兜底
+    try:
+        token_cfg = yml_utils.get(pkg_name or "kaq_quant_common", "api_token")
+        if isinstance(token_cfg, str) and token_cfg.strip():
+            return token_cfg.strip()
+    except Exception as e:
+        # 配置读取失败则视为未配置
+        pass
+    return None
+
+
+def _extract_token_from_authorization(auth_header: Optional[str]) -> Optional[str]:
+    if not auth_header:
+        return None
+    # 支持 Bearer/Token 两种前缀
+    val = auth_header.strip()
+    lower = val.lower()
+    if lower.startswith("bearer "):
+        return val[7:].strip()
+    if lower.startswith("token "):
+        return val[6:].strip()
+    # 若为纯 token 也接受
+    return val
+
+
+def _extract_token_from_headers(headers: Any) -> Optional[str]:
+    # 兼容 Flask/Werkzeug 和 websockets.Headers
+    try:
+        # Flask/requests：大小写不敏感
+        auth = headers.get("Authorization") if hasattr(headers, "get") else None
+        if not auth and hasattr(headers, "get"):
+            auth = headers.get("authorization")
+        token = _extract_token_from_authorization(auth)
+        if token:
+            return token
+        # 备用头
+        x_token = headers.get("X-API-Token") if hasattr(headers, "get") else None
+        if not x_token and hasattr(headers, "get"):
+            x_token = headers.get("x-api-token")
+        return x_token.strip() if isinstance(x_token, str) and x_token.strip() else None
+    except Exception:
+        return None
+
+
+def _extract_token_from_path_query(path: Optional[str]) -> Optional[str]:
+    # 解析 ?token=xxx 简单查询参数
+    if not path or "?" not in path:
+        return None
+    try:
+        query = path.split("?", 1)[1]
+        for pair in query.split("&"):
+            if not pair:
+                continue
+            k, _, v = pair.partition("=")
+            if k.lower() == "token" and v:
+                return v
+    except Exception:
+        pass
+    return None
+
+
+# ----------------- 对外校验方法 -----------------
+
+
+def verify_http_request(flask_request: Any, pkg_name: Optional[str] = None) -> Tuple[bool, Optional[str]]:
+    """校验 HTTP 请求头中的 token。
+    返回 (是否通过, 错误信息)。未配置 token 时默认放行。
+    """
+    expected = _get_expected_token(pkg_name)
+    if not expected:
+        return True, None
+    # 从 Header 提取
+    token = _extract_token_from_headers(getattr(flask_request, "headers", None))
+    if token and token == expected:
+        return True, None
+    return False, "Unauthorized"
+
+
+def verify_ws_handshake(path: Optional[str], headers: Any, pkg_name: Optional[str] = None) -> Tuple[bool, Optional[str]]:
+    """校验 WebSocket 握手阶段的路径与请求头。
+    支持从 Header 与 ?token=xx 解析。未配置 token 时默认放行。
+    """
+    expected = _get_expected_token(pkg_name)
+    if not expected:
+        return True, None
+    # Header 优先
+    token = _extract_token_from_headers(headers)
+    if not token:
+        # 再从路径查询参数解析
+        token = _extract_token_from_path_query(path)
+    if token and token == expected:
+        return True, None
+    return False, "Unauthorized"
+
+
+# ----------------- 客户端复用：获取默认 token -----------------
+
+
+def get_auth_token(pkg_name: Optional[str] = None) -> Optional[str]:
+    """供客户端复用的获取默认 token 的方法。
+    与服务器端校验使用相同的来源规则。
+    """
+    return _get_expected_token(pkg_name)

kaq_quant_common/api/rest/api_client_base.py

@@ -0,0 +1,42 @@
+from typing import Optional, Type, TypeVar
+
+import requests
+from kaq_quant_common.api.common.auth import get_auth_token
+from kaq_quant_common.utils import logger_utils
+from pydantic import BaseModel
+
+R = TypeVar("R", bound=BaseModel)
+
+
+class ApiClientBase:
+    """
+    api 客户端
+    """
+
+    def __init__(self, base_url: str, token: Optional[str] = None):
+        self._base_url = base_url.rstrip("/")
+        self._token = token if token is not None else get_auth_token()
+        self._logger = logger_utils.get_logger(self)
+
+    # 发送请求
+    def _make_request(self, method_name: str, request_data: BaseModel, response_model: Type[R]) -> R:
+        url = f"{self._base_url}/api/{method_name}"
+        headers = {}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        try:
+            # 发送post请求
+            response = requests.post(url, json=request_data.model_dump(), headers=headers or None)
+            # 检查响应状态码，如果不成功，则尝试解析错误信息并抛出异常
+            if not response.ok:
+                try:
+                    error_data = response.json()
+                    error_message = error_data.get("error", response.text)
+                except ValueError:
+                    error_message = response.text
+                raise requests.exceptions.HTTPError(f"HTTP error occurred: {response.status_code} - {error_message}", response=response)
+            # 返回请求结果
+            return response_model(**response.json())
+        except requests.exceptions.RequestException as e:
+            self._logger.error(f"An error occurred: {e}")
+            raise

kaq_quant_common/api/rest/api_server_base.py

@@ -0,0 +1,135 @@
+import inspect
+import threading
+import time
+
+from flask import Flask, jsonify, request
+from werkzeug.serving import make_server
+
+from kaq_quant_common.api.common.api_interface import ApiInterface
+from kaq_quant_common.api.common.auth import verify_http_request
+from kaq_quant_common.utils import logger_utils, signal_utils
+
+
+class ApiServerBase:
+    """
+    API服务器基类，用于动态发现和分派API方法。
+    """
+
+    def __init__(self, api: ApiInterface, host="0.0.0.0", port=5000):
+        """
+        初始化API服务器。
+
+        :param api: 实现了ApiInterface的API实例。
+        :param host: 服务器主机地址。
+        :param port: 服务器端口。
+        """
+        self._app = Flask(__name__)
+        self._api = api
+        self._host = host
+        self._port = port
+        self._server = make_server(self._host, self._port, self._app)
+        self._api_methods = self._discover_api_methods()
+        self._logger = logger_utils.get_logger(self)
+
+        @self._app.route("/api/<method_name>", methods=["POST"])
+        def handle_request(method_name: str):
+            """
+            处理API请求。
+            """
+            # 简单鉴权（若未配置 token 则默认放行）
+            ok, err = verify_http_request(request)
+            if not ok:
+                return jsonify({"error": err or "Unauthorized"}), 401
+
+            if method_name not in self._api_methods:
+                return jsonify({"error": f"Method '{method_name}' not found"}), 404
+
+            method, request_model, response_model = self._api_methods[method_name]
+
+            try:
+                # 使用请求模型验证和解析JSON数据
+                request_data = request_model(**request.json)
+                # 调用API方法
+                response_data = method(request_data)
+                # 验证响应类型
+                if not isinstance(response_data, response_model):
+                    return jsonify({"error": "Invalid response type from method"}), 500
+                # 允许子类包装响应
+                response_data = self._wrap_response(response_data)
+                # 返回JSON响应
+                return jsonify(response_data.model_dump())
+            except Exception as e:
+                # 捕获请求处理过程中的异常
+                return jsonify({"error": str(e)}), 400
+
+    def _discover_api_methods(self):
+        """
+        发现并注册所有使用@api_method装饰器标记的API方法。
+        """
+        methods = {}
+        for name, func in inspect.getmembers(self._api, predicate=inspect.ismethod):
+            if hasattr(func, "_is_api_method") and func._is_api_method:
+                methods[name] = (func, func._request_model, func._response_model)
+        return methods
+
+    # 子类用来包装响应，例如添加时间戳
+    def _wrap_response(self, rsp: any):
+        return rsp
+
+    def run(self):
+        """
+        启动API服务器。
+        """
+        self._logger.info(f"Starting server on {self._host}:{self._port}")
+        self._server.serve_forever()
+
+    def shutdown(self):
+        """
+        关闭API服务器。
+        """
+        self._logger.info(f"Shutting down server on {self._host}:{self._port}")
+        self._server.shutdown()
+
+    def run_with_thread(self, block=True):
+        """
+        启动API服务器在一个新线程中。
+        """
+        self._server_thread = threading.Thread(target=self.run)
+        self._server_thread.name = "ApiServerThread"
+        self._server_thread.daemon = True
+        self._server_thread.start()
+        time.sleep(1)
+
+        if block:
+            self.wait_for_termination()
+
+    def shutdown_with_thread(self):
+        """
+        关闭服务器并等待线程退出
+        """
+        try:
+            self.shutdown()
+        finally:
+            if hasattr(self, "_server_thread") and self._server_thread.is_alive():
+                self._server_thread.join(timeout=3)
+
+    #
+    def wait_for_termination(self):
+        # 全局退出事件，用于传递终止信号
+        exit_event = threading.Event()
+
+        def handle_terminate_signal(signum, frame=None):
+            """信号处理函数：捕获终止信号并触发退出事件"""
+            self._logger.info(f"收到终止信号 {signum}")
+            exit_event.set()
+            # 优雅地停止服务器
+            self.shutdown()
+
+        # 监听信号
+        signal_utils.register_signal_handler(handle_terminate_signal)
+
+        # 监听退出事件
+        while not exit_event.is_set():
+            time.sleep(1)
+
+        self._logger.warning("ApiServer 线程退出")

kaq_quant_common/api/rest/instruction/helper/order_helper.py

@@ -0,0 +1,342 @@
+import json
+import threading
+import time
+from typing import Callable
+
+from kaq_quant_common.api.rest.instruction.models.order import (
+    OrderInfo,
+    OrderSide,
+    OrderStatus,
+    PositionStatus,
+)
+from kaq_quant_common.api.rest.instruction.models.position import PositionSide
+from kaq_quant_common.utils import logger_utils, uuid_utils
+
+
+class OrderHelper:
+    def __init__(self, ins_server):
+        # 必须放在这里 延迟引入，否则会有循环引用问题
+        from kaq_quant_common.api.rest.instruction.instruction_server_base import (
+            InstructionServerBase,
+        )
+
+        self._server: InstructionServerBase = ins_server
+        self._logger = logger_utils.get_logger(self)
+
+        self._mysql_table_name_order = "kaq_futures_instruction_order"
+        self._mysql_table_name_position = "kaq_futures_instruction_position"
+        # 当前持仓
+        self._redis_key_position = "kaq_futures_instruction_position"
+        # 持仓历史
+        self._redis_key_position_history = "kaq_futures_instruction_position_history"
+
+    def _write_position_open_to_redis(
+        self,
+        position_id: str,
+        exchange: str,
+        symbol: str,
+        position_side,
+        coin_quantity: float,
+        usdt_quantity: float,
+        open_ins_id: str,
+        open_price: float,
+        open_fee: float,
+        open_fee_rate: float,
+        open_time: int,
+    ):
+        redis = self._server._redis
+        if redis is None:
+            return
+        data = {
+            "id": position_id,
+            "exchange": exchange,
+            "symbol": symbol,
+            "position_side": position_side.value,
+            "coin_quantity": coin_quantity,
+            "usdt_quantity": usdt_quantity,
+            "open_ins_id": open_ins_id,
+            "open_price": open_price,
+            "open_fee": open_fee,
+            "open_fee_rate": open_fee_rate,
+            "open_time": open_time,
+            "close_ins_id": None,
+            "close_price": 0,
+            "close_time": 0,
+            "status": PositionStatus.OPEN.value,
+        }
+        redis.client.hset(self._redis_key_position, position_id, json.dumps(data))
+
+    def _write_position_close_to_redis(
+        self,
+        position_id: str,
+        exchange: str,
+        symbol: str,
+        position_side,
+        coin_quantity: float,
+        usdt_quantity: float,
+        open_ins_id: str,
+        open_price: float,
+        open_fee: float,
+        open_fee_rate: float,
+        open_time: int,
+        close_ins_id: str,
+        close_price: float,
+        close_fee: float,
+        close_fee_rate: float,
+        close_time: int,
+    ):
+        redis = self._server._redis
+        if redis is None:
+            return
+        
+        # 先从 redis 读取现有的 position 数据，获取 funding_rate_records 字段
+        funding_rate_records = None
+        try:
+            existing_position_json = redis.client.hget(self._redis_key_position, position_id)
+            if existing_position_json:
+                existing_position = json.loads(existing_position_json)
+                if existing_position and "funding_rate_records" in existing_position:
+                    funding_rate_records = existing_position.get("funding_rate_records")
+        except Exception as e:
+            # 读取失败不影响后续流程，记录日志
+            self._logger.warning(f"Failed to get funding_rate_records for position {position_id}: {e}")
+        
+        data = {
+            "id": position_id,
+            "exchange": exchange,
+            "symbol": symbol,
+            "position_side": position_side.value,
+            "coin_quantity": coin_quantity,
+            "usdt_quantity": usdt_quantity,
+            "open_ins_id": open_ins_id,
+            "open_price": open_price,
+            "open_fee": open_fee,
+            "open_fee_rate": open_fee_rate,
+            "open_time": open_time,
+            "close_ins_id": close_ins_id,
+            "close_price": close_price,
+            "close_fee": close_fee,
+            "close_fee_rate": close_fee_rate,
+            "close_time": close_time,
+            "status": PositionStatus.CLOSE.value,
+        }
+        
+        # 如果存在 funding_rate_records，添加到 data 中
+        if funding_rate_records is not None:
+            data["funding_rate_records"] = funding_rate_records
+        
+        redis.client.hdel(self._redis_key_position, position_id)
+        redis.client.rpush(self._redis_key_position_history, json.dumps(data))
+
+    def process_order(self, order: OrderInfo, get_order_result: Callable):
+        # 获取交易所
+        exchange = self._server._exchange
+
+        # 记录时间，统计成交耗时
+        start_time = time.time()
+
+        #
+        if not self._do_process_order(exchange, order, get_order_result, True, start_time):
+            # 马上执行，没有成功，开启线程执行
+            thread = threading.Thread(
+                target=self._do_process_order,
+                args=(exchange, order, get_order_result, False, start_time),
+            )
+            thread.name = f"process_order_{order.instruction_id}_{exchange}_{order.symbol}_{order.order_id}"
+            thread.daemon = True
+            thread.start()
+
+    def _do_process_order(
+        self,
+        exchange: str,
+        order: OrderInfo,
+        get_order_result: Callable,
+        first=True,
+        start_time: float = 0,
+    ):
+        # 获取mysql
+        mysql = self._server._mysql
+
+        #
+        ins_id = order.instruction_id
+        order_id = order.order_id
+        symbol = order.symbol
+        side = order.side
+        position_side = order.position_side
+
+        is_open = True
+        side_str = "开仓"
+        if position_side == PositionSide.LONG:
+            # 多单是正向理解的
+            if side == OrderSide.SELL:
+                side_str = "平仓"
+                is_open = False
+            else:
+                side_str = "开仓"
+                is_open = True
+        else:
+            # 空单是反向理解的
+            if side == OrderSide.SELL:
+                side_str = "开仓"
+                is_open = True
+            else:
+                side_str = "平仓"
+                is_open = False
+
+        if first:
+            self._logger.info(f"{ins_id}_{exchange}_{symbol} step 1. {side_str}挂单成功 {order_id}")
+
+            # 步骤1.挂单成功 插入到订单记录
+            # 获取当前时间-ms
+            current_time = int(time.time() * 1000)
+
+            if mysql is not None:
+                status = OrderStatus.CREATE
+                sql = f"""
+                INSERT INTO {self._mysql_table_name_order} (ins_id, exchange, symbol, side, position_side, orig_price, orig_coin_quantity, order_id, status, create_time, last_update_time) 
+                VALUES ( '{ins_id}', '{exchange}', '{symbol}', '{side.value}', '{order.position_side.value}', {order.target_price}, {order.quantity}, '{order_id}', '{status.value}', {current_time}, {current_time} );
+                """
+                execute_ret = mysql.execute_sql(sql, True)
+
+        # 步骤2.查询订单状态 直到订单成交后
+        # 统计查询次数
+        query_counter = 0
+        while True:
+            query_counter += 1
+            # 获取订单结果
+            order_info = None
+            try:
+                order_info = get_order_result()
+            except Exception as e:
+                self._logger.error(f"{ins_id}_{exchange}_{symbol} step 2. {side_str}订单 查询状态失败 {e}")
+
+            if order_info is not None:
+                break
+            # 只查询一次
+            if first:
+                return False
+            # 等待
+            time.sleep(1)
+
+        if not first:
+            # 需要加上第一查询
+            query_counter += 1
+
+        # 记录时间，统计成交耗时
+        end_time = time.time()
+        cost_time = end_time - start_time
+        self._logger.info(
+            f"{ins_id}_{exchange}_{symbol} step 2. {side_str}订单  {order_id} 成交 耗时 {int(cost_time * 1000)}ms, 查询次数 {query_counter}"
+        )
+
+        # 步骤3.把最终持仓写进去
+        # 平均成交价格 转float
+        avg_price = float(order_info["avg_price"])
+        # 最终成交数量 转float
+        executed_qty = float(order_info["executed_qty"])
+        # 计算出usdt数量
+        executed_usdt = avg_price * executed_qty
+        # 手续费,不一定有
+        fee = float(order_info["fee"]) if "fee" in order_info else 0.0
+        # 费率
+        fee_rate = fee / executed_usdt
+
+        current_time = int(time.time() * 1000)
+
+        if mysql is None:
+            self._logger.warning(f"{ins_id}_{exchange}_{symbol} 仅操作，没有入库，请设置 mysql!!")
+            return
+
+        status = OrderStatus.FINISH
+        # 更新写入最终信息
+        sql = f"""
+        UPDATE {self._mysql_table_name_order} 
+        SET price = {avg_price}, coin_quantity = {executed_qty}, usdt_quantity = {executed_usdt}, fee = {fee}, fee_rate = {fee_rate}, status = '{status.value}', last_update_time = {current_time} 
+        WHERE ins_id = '{ins_id}' AND exchange = '{exchange}' AND symbol = '{symbol}';
+        """
+        execute_ret = mysql.execute_sql(sql, True)
+
+        self._logger.info(
+            f"{ins_id}_{exchange}_{symbol} step 2. 订单成交 {order_id}, {side_str}价格 {avg_price}, {side_str}数量 {executed_qty}, {side_str}usdt {executed_usdt}"
+        )
+        if is_open:
+            # 同时插入持仓表
+            position_id = uuid_utils.generate_uuid()
+            sql = f"""
+            INSERT INTO {self._mysql_table_name_position} (id, exchange, symbol, position_side, coin_quantity, usdt_quantity, open_ins_id, open_price, open_fee, open_fee_rate, open_time, status) 
+            VALUES ( '{position_id}', '{exchange}', '{symbol}', '{position_side.value}', '{executed_qty}', '{executed_usdt}', '{ins_id}', '{avg_price}', '{fee}', '{fee_rate}', {current_time}, '{PositionStatus.OPEN.value}' );
+            """
+            execute_ret = mysql.execute_sql(sql, True)
+
+            self._logger.info(f"{ins_id}_{exchange}_{symbol} step 3. 创建持仓记录 {position_id}")
+            try:
+                self._write_position_open_to_redis(
+                    position_id,
+                    exchange,
+                    symbol,
+                    position_side,
+                    executed_qty,
+                    executed_usdt,
+                    ins_id,
+                    avg_price,
+                    fee,
+                    fee_rate,
+                    current_time,
+                )
+            except:
+                pass
+        else:
+            # 需要找到对应的持仓记录
+            sql = f"""
+            SELECT * FROM {self._mysql_table_name_position}
+            WHERE exchange = '{exchange}' AND symbol = '{symbol}' AND position_side = '{position_side.value}' AND status = '{PositionStatus.OPEN.value}' 
+            ORDER BY open_time ASC;
+            """
+
+            # 如果有指定仓位id，就用指定的
+            if hasattr(order, "position_id") and order.position_id:
+                sql = f"""
+                SELECT * FROM {self._mysql_table_name_position}
+                WHERE id = '{order.position_id}' AND status = '{PositionStatus.OPEN.value}'
+                """
+                self._logger.info(f"{ins_id}_{exchange}_{symbol} get position by id {order.position_id}")
+
+            execute_ret = mysql.execute_sql(sql)
+            try:
+                row = execute_ret.fetchone()
+                position_id = row.id
+                if position_id is not None:
+                    # 更新持仓信息
+                    sql = f"""
+                    UPDATE {self._mysql_table_name_position} 
+                    SET close_ins_id = '{ins_id}', close_price = {avg_price}, close_fee = '{fee}', close_fee_rate = '{fee_rate}', close_time = {current_time}, status = '{PositionStatus.CLOSE.value}'
+                    WHERE id = '{position_id}';
+                    """
+                    execute_ret = mysql.execute_sql(sql, True)
+
+                    self._logger.info(f"{ins_id}_{exchange}_{symbol} step 3. 更新持仓记录 {position_id}")
+                    try:
+                        self._write_position_close_to_redis(
+                            position_id,
+                            exchange,
+                            symbol,
+                            position_side,
+                            float(row.coin_quantity),
+                            float(row.usdt_quantity),
+                            row.open_ins_id,
+                            float(row.open_price),
+                            float(row.open_fee),
+                            float(row.open_fee_rate),
+                            int(row.open_time),
+                            ins_id,
+                            avg_price,
+                            fee,
+                            fee_rate,
+                            current_time,
+                        )
+                    except:
+                        pass
+            except:
+                pass
+
+        return True