feat(trade_manager): 添加按股票获取扩展持仓详情功能

Author: fasiondog

docs/source/trade_manage/TradeManager.rst

@@ -555,14 +555,36 @@
         :param int trade_mode: 交易模式，影响部分统计项：0-收盘时交易，1-下一开盘时交易
         :return: 持仓扩展详情列表
 
-    .. py:method:: get_position_ext_info(self, current_time, ktype=Query.DAY, trade_mode=0) -> dict
+    .. py:method:: get_position_ext_info(self, stock, current_time, ktype=Query.DAY, trade_mode=0) -> PositionExtInfo
     
-        获取账户最后交易时刻之后指定时间的持仓详情，以字典返回，stock 为 key, PositionExtInfo 为 value
+        获取账户指定时刻的扩展持仓详情（仅针对指定股票）
 
+        :param Stock stock: 指定股票
         :param Datetime current_time: 当前时刻（需大于等于最后交易时刻）
-        :param Query.KType ktype: k 线类型
-        :param int trade_mode: 交易模式，影响部分统计项：0-收盘时交易，1-下一开盘时交易
-        :return: 持仓扩展详情字典
+        :param Query.KType ktype: K 线类型，默认日线
+        :param int trade_mode: 交易模式，影响部分统计项：0-收盘时交易，1-下一开盘时交易，默认 0
+        :return: 扩展持仓详情，包含以下字段：
+        
+            - position (PositionRecord): 基础持仓记录
+            - max_high_price (float): 期间最高价最大值
+            - min_low_price (float): 期间最低价最小值
+            - max_close_price (float): 期间收盘价最高值
+            - min_close_price (float): 期间收盘价最低值
+            - current_close_price (float): 当前收盘价
+            - max_pull_back1 (float): 最大回撤百分比 1（仅使用最大收盘价和最低收盘价计算）（负数）
+            - max_pull_back2 (float): 最大回撤百分比 2（使用期间最高价最大值和最低价最小值计算）（负数）
+            - current_profit (float): 当前浮动盈亏（不含预计卖出成本）
+            
+            以及以下计算方法：
+            
+            - current_pull_back1(): 当前回撤百分比 1（仅使用最大收盘价和当前收盘价计算）
+            - current_pull_back2(): 当前回撤百分比 2（使用期间最高价最大值和当前收盘价计算）
+            - max_floating_profit1(): 期间最大浮盈百分比 1（仅使用收盘价计算，不含预计卖出成本，多次买卖时统计不准）
+            - max_floating_profit2(): 期间最大浮盈百分比 2（使用最高价最大值进行计算，不含预计卖出成本，多次买卖时统计不准）
+            - min_loss_profit1(): 期间最大浮亏百分比 1（仅使用收盘价计算，不含预计卖出成本，多次买卖时统计不准）
+            - min_loss_profit2(): 期间最大浮亏百分比 2（仅使用期间最低价计算，不含预计卖出成本，多次买卖时统计不准）
+            
+        :note: 该功能只适合一买一卖的情况，对于一买多卖的情况，部分统计可能不准确，仅供参考
 
     .. py:method:: get_history_position_ext_info_list(self, ktype=Query.DAY, trade_mode=0) -> list[PositionExtInfo]
           

hikyuu_cpp/hikyuu/plugin/interface/TMReportPluginInterface.h

@@ -49,12 +49,24 @@ class TMReportPluginInterface : public PluginBase {
                                                                 const KQuery::KType& ktype,
                                                                 int trade_mode) = 0;
 
+    /**
+     * @brief 获取账户指定时刻的指定证券的持仓详情
+     * @param tm 账户
+     * @param stock 持仓的股票
+     * @param current_time 当前时刻（需大于等于最后交易时刻）
+     * @param ktype k线类型
+     * @param trade_mode 交易模式，影响部分统计项: 0-收盘时交易, 1-下一开盘时交易
+     * @return PositionExtInfo
+     */
+    virtual PositionExtInfo getPositionExtInfo(const TMPtr& tm, const Stock& stock,
+                                               const Datetime& current_time,
+                                               const KQuery::KType& ktype, int trade_mode) = 0;
+
     /**
      * 统计截至某一时刻的系统绩效, datetime必须大于等于lastDatetime，
      * 以便用于计算当前市值
      * @param tm 指定的交易管理实例
      * @param datetime 统计截止时刻
-     * @param ktype k线类型
      */
     virtual Performance getExtPerformance(const TMPtr& tm, const Datetime& datetime,
                                           const KQuery::KType& ktype) = 0;

hikyuu_cpp/hikyuu/trade_manage/TradeManagerBase.cpp

@@ -85,6 +85,17 @@ std::unordered_map<Stock, PositionExtInfo> TradeManagerBase::getPositionExtInfoD
     return ret;
 }
 
+PositionExtInfo TradeManagerBase::getPositionExtInfo(const Stock& stock,
+                                                     const Datetime& current_time,
+                                                     const KQuery::KType& ktype, int trade_mode) {
+    PositionExtInfo ret;
+    auto& sm = StockManager::instance();
+    auto* plugin = sm.getPlugin<TMReportPluginInterface>(HKU_PLUGIN_TMREPORT);
+    HKU_ERROR_IF_RETURN(!plugin, ret, "Can't find {} plugin!", HKU_PLUGIN_TMREPORT);
+    ret = plugin->getPositionExtInfo(shared_from_this(), stock, current_time, ktype, trade_mode);
+    return ret;
+}
+
 std::vector<std::pair<Datetime, double>> TradeManagerBase::getProfitPercentMonthly(
   const Datetime& datetime) {
     std::vector<std::pair<Datetime, double>> ret;

hikyuu_cpp/hikyuu/trade_manage/TradeManagerBase.h

@@ -768,6 +768,14 @@ class HKU_API TradeManagerBase : public enable_shared_from_this<TradeManagerBase
       const Datetime& datetime = Datetime::now(), const KQuery::KType& ktype = KQuery::DAY,
       int trade_mode = 0);
 
+    /**
+     * 获取账户最后交易时刻后持仓详情
+     */
+    PositionExtInfo getPositionExtInfo(const Stock& stock,
+                                       const Datetime& current_time = Datetime::now(),
+                                       const KQuery::KType& ktype = KQuery::DAY,
+                                       int trade_mode = 0);
+
     /**
      * @brief 获取指定截止时间前各月的收益百分比
      * @param datetime

hikyuu_pywrap/trade_manage/_TradeManager.cpp

@@ -618,6 +618,41 @@ void export_TradeManager(py::module& m) {
     :param Query.KType ktype: k线类型
     :return: 最大回撤百分比)")
 
+      .def(
+        "get_position_ext_info", &TradeManagerBase::getPositionExtInfo, py::arg("stock"),
+        py::arg("current_time"), py::arg("ktype") = KQuery::DAY, py::arg("trade_mode") = 0,
+        R"(get_position_ext_info(self, stock, current_time, ktype=Query.DAY, trade_mode=0) -> PositionExtInfo)
+
+        获取账户指定时刻的扩展持仓详情（仅针对指定股票）
+
+        :param Stock stock: 指定股票
+        :param Datetime current_time: 当前时刻（需大于等于最后交易时刻）
+        :param Query.KType ktype: K 线类型，默认日线
+        :param int trade_mode: 交易模式，影响部分统计项：0-收盘时交易，1-下一开盘时交易，默认 0
+        :return: 扩展持仓详情，包含以下字段：
+        
+            - position (PositionRecord): 基础持仓记录
+            - max_high_price (float): 期间最高价最大值
+            - min_low_price (float): 期间最低价最小值
+            - max_close_price (float): 期间收盘价最高值
+            - min_close_price (float): 期间收盘价最低值
+            - current_close_price (float): 当前收盘价
+            - max_pull_back1 (float): 最大回撤百分比 1（仅使用最大收盘价和最低收盘价计算）（负数）
+            - max_pull_back2 (float): 最大回撤百分比 2（使用期间最高价最大值和最低价最小值计算）（负数）
+            - current_profit (float): 当前浮动盈亏（不含预计卖出成本）
+            
+            以及以下计算方法：
+            
+            - current_pull_back1(): 当前回撤百分比 1（仅使用最大收盘价和当前收盘价计算）
+            - current_pull_back2(): 当前回撤百分比 2（使用期间最高价最大值和当前收盘价计算）
+            - max_floating_profit1(): 期间最大浮盈百分比 1（仅使用收盘价计算，不含预计卖出成本，多次买卖时统计不准）
+            - max_floating_profit2(): 期间最大浮盈百分比 2（使用最高价最大值进行计算，不含预计卖出成本，多次买卖时统计不准）
+            - min_loss_profit1(): 期间最大浮亏百分比 1（仅使用收盘价计算，不含预计卖出成本，多次买卖时统计不准）
+            - min_loss_profit2(): 期间最大浮亏百分比 2（仅使用期间最低价计算，不含预计卖出成本，多次买卖时统计不准）
+            
+        :note: 该功能只适合一买一卖的情况，对于一买多卖的情况，部分统计可能不准确，仅供参考
+        )")
+
       .def(
         "get_position_ext_info_list", &TradeManagerBase::getPositionExtInfoList,
         py::arg("current_time"), py::arg("ktype") = KQuery::DAY, py::arg("trade_mode") = 0,