zszq-trs/YLErpDAL/Modules/SwapModule/ARCHITECTURE.md

SwapModule 架构说明

本文档描述 2026-08 重构后的模块结构。所有改动均通过编译 + 全量测试验证（零回归）。

三大限界上下文

TRS 的三类业务各自独立，通过 SwapInterest 纯函数库共享计息能力：

                    SwapInterest (Core 纯函数)
                    "本金 × 利率 × 天数 / 年化"
                    不依附于任何腿
                         ↑
          ┌──────────────┼──────────────┐
          │ 谁需要算利息就调它            │
          │                            │
    ┌─────┴──────┐              ┌──────┴───────┐
    │ FundingLeg  │              │ Margin       │
    │ 融资腿      │              │ 保证金       │
    │             │              │              │
    │ 客户付券商   │              │ 客户交的抵押品│
    │ 的融资成本   │              │              │
    │ spread+FR007│              │ 余额/追保/返还│
    │ mode 1/2/9  │              │ mode 5/6     │
    └─────────────┘              └──────────────┘

    ┌─────────────┐
    │ ReturnLeg    │
    │ 标的端       │
    │             │
    │ 标的总回报   │
    │ 价格+分红    │
    └─────────────┘

命名规则（防歧义）：

• Funding = 融资成本（不用 Interest，避免和通用"利息"混）
• Return = 标的总回报（不用 Float，避免和 FR007 浮动利率混）
• Margin = 保证金（客户交的抵押品，有余额和返息，不走融资腿的计息基数框架）
• FloatRate = FR007 浮动利率（唯一含义）

目录结构

SwapModule/
├── FundingLegs/               融资腿（mode 1/2/9）
│   ├── IFundingLegStrategy    策略接口 + NotionalResult 值对象
│   ├── FixedAmountLeg         mode 1 固定值（恒=Fix 不随比例变）
│   ├── ContractNotionalLeg    mode 2 合约名义本金规模
│   ├── UnderlyingEntryFullPriceLeg  mode 9 标的期初全价
│   └── FundingLegStrategyFactory   按 mode 分发
│
├── Margin/                    保证金（mode 5/6）
│   ├── MarginModes            mode 判断（含 ForLinq for EF Core）
│   ├── MarginBalance          保证金余额（值对象）
│   ├── MarginAccount          余额管理 + AccrueInterest 计息入口
│   ├── MarginCalc             纯函数（PreviousBalance/FlipDirection/AccumulateSettlement）
│   ├── IMarginResolver        保证金形态接口
│   └── Cash/Credit/Guarantee  三种形态实现
│
├── ReturnLegs/                标的端
│   ├── ReturnLegSummary       标的端汇总值
│   ├── QtyRollforward         数量递推（预留 corpActionDeltaQty 给公司行为）
│   ├── MtmCalc                盯市（MarketValue + UnrealizedPnl）
│   ├── DividendCalc           增值税后票息（AfterTax + AfterTaxRaw）
│   ├── DirectionRatio         方向因子（LongShort + ReceivePay）
│   └── PositionValueCalc      持仓价值汇总（利息端 + 浮动端）
│
├── SwapDealService.cs         盘中平仓/互换主逻辑
├── SwapEodPositionService.cs  EOD 日终归档主逻辑
├── SwapDealIndexFixer.cs      SwapDealService 专用取价器（委托 TryGetFloatRate）
└── Fr007IndexFixer.cs         FR007 取价生产实现

Core 层（Framework/YLErp.Core/Interest/）

Interest/
├── SwapInterest.cs            纯函数库（AccrueSimple/AccrueCompound/ApplyUnwind）
├── IIndexFixer.cs             取价接口
├── IndexFixerBase.cs          取价日计算工具
└── Fr007IndexFixer.cs         FR007 取价生产实现（调 EodPriceQueryService）

InterestModeEnum（显式赋值，DB 契约）

Unknown = 0
固定值 = 1            → FundingLeg
合约名义本金规模 = 2   → FundingLeg
初始预付金 = 5         → Margin
追加预付金 = 6         → Margin
标的期初全价 = 9       → FundingLeg

已删除（无历史数据）：
  3 = 持仓名义本金（死代码）
  4 = 持仓市值（死代码）
  7 = 多头存续名义本金（界面已禁用）
  8 = 空头存续名义本金（界面已禁用）

已消除的 inline 重复

公式	原重复	收敛到
FR007 取价	6处	IIndexFixer
保证金 mode 判断	10处	MarginModes
UnderlyingMarketValue	4处	MtmCalc.MarketValue
PosiMtmPnL	4处	MtmCalc.UnrealizedPnl
PosiQuantity 递推	2行	QtyRollforward.Calc
增值税公式	5处	DividendCalc
方向因子三元式	7处	DirectionRatio
SwapPositionValue	8处	PositionValueCalc
CalcNotionalByMode	整个方法	已删除（融资腿走工厂，保证金内联）

方向因子类型规范

所有方向因子（多空 +1/-1、收付 +1/-1）统一用 int，不用 decimal：

纯函数	参数	类型
MtmCalc.MarketValue	shortRatio	int
MtmCalc.UnrealizedPnl	shortRatio, ratio	int
DirectionRatio.LongShort	返回值	int
DirectionRatio.ReceivePay	返回值	int
MarginCalc.FlipDirection	返回值	int
PositionValueCalc.Calc	ratio	int

待后续改造

项目	依赖	接缝已预留
公司行为（送股/拆股）	QtyRollforward.corpActionDeltaQty	✅
公司行为（登记日快照）	DividendCalc + BondPayment	见 corp-action-refactor-proposal.md
保证金配置/规则/占用	MarginAccount + MarginCalc	✅
RecordMarginCashFlow 迁入 Margin	AddClientCash 加 virtual	待做
EOD 编排拆分	SwapPositionCompose	待业务需求驱动