From e73272042ad77903b8ec1254b2dc13bfcc3fa432 Mon Sep 17 00:00:00 2001
From: hjhan <hongjun.han@yieldchain.com>
Date: Tue, 11 Aug 2026 10:15:20 +0800
Subject: [PATCH] =?UTF-8?q?refactor(return-leg):=20=E6=96=B0=E5=A2=9E=20Re?=
 =?UTF-8?q?turnLegSummary=20=E6=A0=87=E7=9A=84=E7=AB=AF=E5=80=BC=E5=AF=B9?=
 =?UTF-8?q?=E8=B1=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

标的端(Total Return Leg)归档产出的汇总值: 多空名义本金/平仓名义本金/含费全价。
对应原 SwapPositionCompose 里 DealFloatPositions 传给 DealInterests 的4个标量。

命名说明(防歧义):
- 用 ReturnLeg(业界标准 Total Return Leg), 不用 FloatLeg
- 'float'在金融里首要含义是'浮动利率'(如FR007), 用于标的端会产生歧义
- 标的端 = 标的资产的总回报(价格涨跌+票息分红), 与浮动利率无关

纯新增骨架, 零生产改动。
验证: 编译0错误, 3个单测全过, 全量489测试7失败(基线一致)。
---
 .../ReturnLegs/ReturnLegSummaryTest.cs        | 46 +++++++++++++++++++
 .../SwapModule/ReturnLegs/ReturnLegSummary.cs | 31 +++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 UnitTestProject/Modules/SwapModule/ReturnLegs/ReturnLegSummaryTest.cs
 create mode 100644 YLErpDAL/Modules/SwapModule/ReturnLegs/ReturnLegSummary.cs

diff --git a/UnitTestProject/Modules/SwapModule/ReturnLegs/ReturnLegSummaryTest.cs b/UnitTestProject/Modules/SwapModule/ReturnLegs/ReturnLegSummaryTest.cs
new file mode 100644
index 00000000..61f9a69c
--- /dev/null
+++ b/UnitTestProject/Modules/SwapModule/ReturnLegs/ReturnLegSummaryTest.cs
@@ -0,0 +1,46 @@
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+using YLErp.Modules.SwapModule.ReturnLegs;
+
+namespace UnitTestProject.Modules.SwapModule.ReturnLegs
+{
+    /// <summary>
+    /// ReturnLegSummary 值对象测试。
+    /// 验证标的端归档产出的汇总值正确构造、字段语义清晰。
+    /// </summary>
+    [TestClass]
+    public class ReturnLegSummaryTest
+    {
+        [TestMethod]
+        public void 构造_四个字段正确赋值()
+        {
+            var s = new ReturnLegSummary(
+                longNotional: 100_000_000m,
+                shortNotional: 0m,
+                closeNotional: 50_000_000m,
+                grossPrice: 1.02m);
+
+            Assert.AreEqual(100_000_000m, s.LongNotional);
+            Assert.AreEqual(0m, s.ShortNotional);
+            Assert.AreEqual(50_000_000m, s.CloseNotional);
+            Assert.AreEqual(1.02m, s.GrossPrice);
+        }
+
+        [TestMethod]
+        public void 构造_空头场景()
+        {
+            var s = new ReturnLegSummary(0m, 80_000_000m, 30_000_000m, 0.98m);
+
+            Assert.AreEqual(0m, s.LongNotional, "无多头");
+            Assert.AreEqual(80_000_000m, s.ShortNotional, "空头名义本金");
+        }
+
+        [TestMethod]
+        public void 构造_全平场景()
+        {
+            var s = new ReturnLegSummary(0m, 0m, 100_000_000m, 1.00m);
+
+            Assert.AreEqual(100_000_000m, s.CloseNotional, "全平：平仓名义本金=全额");
+            Assert.AreEqual(0m, s.LongNotional, "全平后无多头剩余");
+        }
+    }
+}
diff --git a/YLErpDAL/Modules/SwapModule/ReturnLegs/ReturnLegSummary.cs b/YLErpDAL/Modules/SwapModule/ReturnLegs/ReturnLegSummary.cs
new file mode 100644
index 00000000..442d64aa
--- /dev/null
+++ b/YLErpDAL/Modules/SwapModule/ReturnLegs/ReturnLegSummary.cs
@@ -0,0 +1,31 @@
+namespace YLErp.Modules.SwapModule.ReturnLegs;
+
+/// <summary>
+/// 标的端(Total Return Leg)归档产出的汇总值。
+///
+/// 这些值由标的盯市+分红计算得出，传给融资端(FundingLeg)作为计息基数参考。
+/// 对应原 SwapPositionCompose 里 DealFloatPositions 的产出：
+///   posiLongNotional / posiShortNotional / closePosiNotional / grossPrice
+///
+/// 命名说明：这里叫 ReturnLeg（业界标准 Total Return Leg），不叫 FloatLeg——
+/// "float" 在金融里首要含义是"浮动利率"(如 FR007)，用于标的端会产生歧义。
+/// 标的端 = 标的资产的总回报(价格涨跌 + 票息/分红)，与浮动利率无关。
+/// </summary>
+public readonly struct ReturnLegSummary
+{
+    /// <summary>多头剩余名义本金(= 数量 × 全价)。融资端用它算多头腿计息基数。</summary>
+    public decimal LongNotional { get; }
+
+    /// <summary>空头剩余名义本金。</summary>
+    public decimal ShortNotional { get; }
+
+    /// <summary>本次平仓名义本金(平仓数量 × 合约乘数 × 含费全价)。</summary>
+    public decimal CloseNotional { get; }
+
+    /// <summary>标的含费全价(PosiGrossPrice / EntryDirtyPrice)。融资端 mode 9 衡泰路径折算用。</summary>
+    public decimal GrossPrice { get; }
+
+    public ReturnLegSummary(decimal longNotional, decimal shortNotional, decimal closeNotional, decimal grossPrice)
+        => (LongNotional, ShortNotional, CloseNotional, GrossPrice)
+         = (longNotional, shortNotional, closeNotional, grossPrice);
+}