feat(interest): 新增 InterestTrace 结构化追踪收集器

纯值对象(零日志依赖)：计息纯函数把"发生了什么"记录为语义化条目 (Day/ResetBefore/ResetAfter/Rollover/Unwind)，由适配器统一经 SwapCalcTrace 常驻落盘。ToString 产出稳定可 diff 的逐行文本，新旧引擎同一笔交易可直接 diff 定位"是计算变了还是重构引入漂移"。
2026-08-12 06:05:01 +08:00
parent 63bfc8ca8f
commit 03861ea369
1 changed files with 78 additions and 0 deletions
@@ -0,0 +1,78 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using YLErp.Derivatives.Interest;
+
+namespace YLErp.Core.Interest;
+
+/// <summary>
+/// 计息过程追踪收集器（值对象，非日志）。
+///
+/// <para><b>为什么是收集器而不是日志调用</b>：计息数学（SwapInterest / FundingLegAccrual）必须保持纯函数、
+/// 可单测、不依赖 NLog；但按工程铁律，关键路径日志须<b>无条件常驻落盘</b>（出问题时事后翻日志定位，不能依赖开关）。
+/// 折中：纯函数把"发生了什么"记录为结构化条目写入本收集器，由<b>适配器(IO 边界)</b>统一经
+/// <c>SwapCalcTrace.Persist</c> 常驻落盘。落盘职责归一处，计息代码零日志依赖、保持干净。</para>
+///
+/// <para><b>可 diff</b>：<see cref="ToString"/> 产出稳定、有序、与 SwapCalcTrace.Day 对齐的逐行文本，
+/// 新旧引擎对同一笔交易跑出的 trace 可直接 diff，定位"是计算变了还是重构引入了漂移"。</para>
+///
+/// <para>所有记录方法均为语义化命名（Day / ResetBefore / Rollover …），调用点一眼即懂，不污染数学可读性。</para>
+/// </summary>
+public sealed class InterestTrace
+{
+    private readonly List<InterestTraceEntry> _entries = new();
+
+    /// <summary>已记录的追踪条目（只读）。</summary>
+    public IReadOnlyList<InterestTraceEntry> Entries => _entries;
+
+    /// <summary>计息区间起点：标记本次计算的整体边界与年化口径。</summary>
+    public void MarkStart(DateTime start, DateTime end, AccrualBoundary boundary, int annualDays, bool annualized)
+        => Add(InterestStep.Start, start,
+            $"START 区间[{start:yyyy-MM-dd},{end:yyyy-MM-dd}] {boundary} annualDays={annualDays} annualized={annualized}");
+
+    /// <summary>逐日明细：当日生效利率、计息基数、当日利息、累计利息。这是"为何 accrued N 天而非 M 天"的直接证据。</summary>
+    public void Day(int idx, DateTime date, decimal rate, decimal basePrincipal, decimal dayInterest, decimal accumulated)
+        => Add(InterestStep.DayAccrual, date,
+            $"  [{idx}] {date:yyyy-MM-dd} rate={rate:P6} base={basePrincipal:F4} day={dayInterest:F6} acc={accumulated:F6}");
+
+    /// <summary>重置日<b>前</b>：生效利率(旧)与计息本金(滚动前)。利率/本金切换的"因"。</summary>
+    public void ResetBefore(DateTime resetDate, decimal rateOld, decimal principalBefore)
+        => Add(InterestStep.ResetBefore, resetDate,
+            $"  RESET↓ {resetDate:yyyy-MM-dd} rate(old)={rateOld:P6} principal(before)={principalBefore:F4}");
+
+    /// <summary>重置日<b>后</b>：生效利率(新)与计息本金(滚动后，已并本金)。利率/本金切换的"果"。</summary>
+    public void ResetAfter(DateTime resetDate, decimal rateNew, decimal principalAfter)
+        => Add(InterestStep.ResetAfter, resetDate,
+            $"  RESET↑ {resetDate:yyyy-MM-dd} rate(new)={rateNew:P6} principal(after)={principalAfter:F4}");
+
+    /// <summary>本金增加（利息滚入计息基数）：复利段末并本金的瞬间，记录滚入额与并本金后的新基数。</summary>
+    public void Rollover(DateTime resetDate, decimal accruedRolled, decimal newBasis)
+        => Add(InterestStep.Rollover, resetDate,
+            $"  ROLLOVER {resetDate:yyyy-MM-dd} accrued(rolled)={accruedRolled:F6} newBasis={newBasis:F4}");
+
+    /// <summary>平仓缩放：平仓比例、累计已实现、剩余未实现。</summary>
+    public void Unwind(DateTime date, decimal unwindPercent, decimal realized, decimal remainingUnrealized)
+        => Add(InterestStep.Unwind, date,
+            $"  UNWIND {date:yyyy-MM-dd} pct={unwindPercent:P2} realized={realized:F6} remaining={remainingUnrealized:F6}");
+
+    /// <summary>收尾：最终累计利息与当日利息。</summary>
+    public void MarkEnd(decimal totalAccrued, decimal totalToday)
+        => Add(InterestStep.End, default,
+            $"END accrued={totalAccrued:F6} today={totalToday:F6}");
+
+    private void Add(InterestStep step, DateTime date, string line)
+        => _entries.Add(new InterestTraceEntry(step, date, line));
+
+    /// <summary>稳定可 diff 的逐行文本（与 SwapCalcTrace.Day 格式对齐）。</summary>
+    public override string ToString()
+        => _entries.Count == 0 ? "<empty trace>" : string.Join(Environment.NewLine, _entries.Select(e => e.Line));
+}
+
+/// <summary>追踪条目的语义类别，便于程序化筛选（如"只看重置日"）。</summary>
+public enum InterestStep
+{
+    Start, DayAccrual, ResetBefore, ResetAfter, Rollover, Unwind, End
+}
+
+/// <summary>单条追踪记录：类别 + 日期 + 已渲染文本。</summary>
+public readonly record struct InterestTraceEntry(InterestStep Step, DateTime Date, string Line);