完善手工回放的最终费用和真实观察时间合同

2026-09-14 10:15:03 +08:00
parent a29c434be9
commit 665653c3fe
3 changed files with 216 additions and 56 deletions
@@ -1,7 +1,7 @@
 //! Confirmed manual fills are external observations, not simulated broker fills.
 //! The producer must bind these records to the runtime's durable order/audit facts.

-use std::collections::BTreeSet;
+use std::collections::{BTreeMap, BTreeSet};

 use chrono::{DateTime, FixedOffset, NaiveDate, Timelike, Utc};
 use rust_decimal::Decimal;
@@ -12,7 +12,7 @@ use crate::events::OrderSide;
 use crate::{DataSet, FixedMoney, PortfolioState};
 use rust_decimal::prelude::ToPrimitive;

-pub const MANUAL_REPLAY_SCHEMA: &str = "fidc.observed-manual-executions/v1";
+pub const MANUAL_REPLAY_SCHEMA: &str = "fidc.observed-manual-executions/v2";

 #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
 #[serde(deny_unknown_fields, rename_all = "camelCase")]
@@ -33,6 +33,7 @@ pub struct ManualExecutionAction {
    pub source: ManualExecutionSource,
    pub audit_event_ids: Vec<String>,
    pub confirmed_at: DateTime<Utc>,
+    pub confirmation_observed_at: DateTime<Utc>,
    pub outcome: ManualActionOutcome,
    pub orders: Vec<ManualExecutionOrder>,
 }
@@ -41,6 +42,7 @@ pub struct ManualExecutionAction {
 #[serde(rename_all = "snake_case")]
 pub enum ManualActionOutcome {
    NoOrdersNeeded,
+    NotExecuted,
    OrdersTerminal,
 }

@@ -58,12 +60,12 @@ pub enum ManualExecutionSource {
 pub struct ManualExecutionOrder {
    pub order_id: String,
    pub broker_order_id: Option<String>,
-    pub source_adapter: String,
+    pub source_adapter: Option<String>,
    pub symbol: String,
    pub side: OrderSide,
    pub quantity: u32,
-    pub submitted_at: DateTime<Utc>,
-    pub terminal_at: DateTime<Utc>,
+    pub order_created_at: DateTime<Utc>,
+    pub terminal_observed_at: DateTime<Utc>,
    pub terminal_status: ManualOrderTerminalStatus,
    pub fills: Vec<ManualExecutionFill>,
 }
@@ -83,6 +85,9 @@ pub struct ManualExecutionFill {
    pub trade_id: String,
    pub observation_event_id: String,
    pub observation_sequence: u64,
+    pub fee_observation_event_id: String,
+    pub fee_observation_sequence: u64,
+    pub fee_observed_at: DateTime<Utc>,
    pub trade_date: NaiveDate,
    pub executed_at: DateTime<Utc>,
    pub observed_at: DateTime<Utc>,
@@ -90,12 +95,15 @@ pub struct ManualExecutionFill {
    pub quantity: u32,
    #[serde(with = "rust_decimal::serde::str")]
    pub price: Decimal,
+    #[serde(default, with = "rust_decimal::serde::str_option")]
+    pub commission: Option<Decimal>,
+    #[serde(default, with = "rust_decimal::serde::str_option")]
+    pub stamp_tax: Option<Decimal>,
+    #[serde(default, with = "rust_decimal::serde::str_option")]
+    pub transfer_fee: Option<Decimal>,
+    /// Full observed charge, including any venue fees not itemized above.
    #[serde(with = "rust_decimal::serde::str")]
-    pub commission: Decimal,
-    #[serde(with = "rust_decimal::serde::str")]
-    pub stamp_tax: Decimal,
-    #[serde(with = "rust_decimal::serde::str")]
-    pub transfer_fee: Decimal,
+    pub total_fee: Decimal,
 }

 #[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
@@ -126,10 +134,19 @@ impl ManualExecutionFill {
    }

    pub fn total_fees(&self) -> Result<Decimal, String> {
-        self.commission
-            .checked_add(self.stamp_tax)
-            .and_then(|sum| sum.checked_add(self.transfer_fee))
-            .ok_or_else(|| "manual fill fees overflow".into())
+        let known = [self.commission, self.stamp_tax, self.transfer_fee]
+            .into_iter()
+            .flatten()
+            .try_fold(Decimal::ZERO, |sum, fee| {
+                if fee < Decimal::ZERO {
+                    return Err("manual fill fee component is negative");
+                }
+                sum.checked_add(fee).ok_or("manual fill fees overflow")
+            })?;
+        if self.total_fee < known {
+            return Err("manual total fee is below its known components".into());
+        }
+        Ok(self.total_fee)
    }
 }

@@ -200,17 +217,22 @@ impl ManualExecutionReplay {
        let mut trades = BTreeSet::new();
        let mut observation_events = BTreeSet::new();
        let mut observation_sequences = BTreeSet::new();
+        let mut fee_observations = BTreeSet::new();
+        let mut receipt_ids = BTreeMap::new();
+        let mut receipt_sequences = BTreeMap::new();
        for action in &self.actions {
            identifier(&action.action_id)?;
            if !actions.insert(action.action_id.as_str())
                || action.confirmed_at > self.observation_cutoff
+                || action.confirmation_observed_at < action.confirmed_at
+                || action.confirmation_observed_at > self.observation_cutoff
            {
                return Err("duplicate manual action or confirmation after cutoff".into());
            }
            if action.audit_event_ids.is_empty() {
                return Err("manual action has no immutable audit binding".into());
            }
-            if (action.outcome == ManualActionOutcome::NoOrdersNeeded) != action.orders.is_empty() {
+            if (action.outcome != ManualActionOutcome::OrdersTerminal) != action.orders.is_empty() {
                return Err("manual action outcome does not prove its order coverage".into());
            }
            for id in &action.audit_event_ids {
@@ -221,20 +243,28 @@ impl ManualExecutionReplay {
            }
            for order in &action.orders {
                identifier(&order.order_id)?;
-                identifier(&order.source_adapter)?;
+                if let Some(adapter) = &order.source_adapter {
+                    identifier(adapter)?;
+                }
                identifier(&order.symbol)?;
                if let Some(id) = &order.broker_order_id {
                    identifier(id)?;
                    if !broker_orders.insert((
-                        order.source_adapter.as_str(),
-                        order.submitted_at.with_timezone(&shanghai).date_naive(),
+                        order
+                            .source_adapter
+                            .as_deref()
+                            .ok_or("broker identity requires its source adapter")?,
+                        order.order_created_at.with_timezone(&shanghai).date_naive(),
                        id.as_str(),
                    )) {
                        return Err("manual local orders share one broker order identity".into());
                    }
                }
+                if !order.fills.is_empty() && order.source_adapter.is_none() {
+                    return Err("manual fills require a known source adapter".into());
+                }
                if !order.fills.is_empty()
-                    && order.source_adapter != "paper"
+                    && order.source_adapter.as_deref() != Some("paper")
                    && order.broker_order_id.is_none()
                {
                    return Err(
@@ -247,9 +277,9 @@ impl ManualExecutionReplay {
                {
                    return Err("duplicate manual order or invalid quantity".into());
                }
-                if order.submitted_at < action.confirmed_at
-                    || order.terminal_at < order.submitted_at
-                    || order.terminal_at > self.observation_cutoff
+                if order.order_created_at < action.confirmed_at
+                    || order.terminal_observed_at < order.order_created_at
+                    || order.terminal_observed_at > self.observation_cutoff
                {
                    return Err(
                        "manual order confirmation/submission/terminal time is inconsistent".into(),
@@ -259,6 +289,7 @@ impl ManualExecutionReplay {
                for fill in &order.fills {
                    identifier(&fill.trade_id)?;
                    identifier(&fill.observation_event_id)?;
+                    identifier(&fill.fee_observation_event_id)?;
                    if fill.observation_sequence == 0
                        || fill.observation_sequence > i64::MAX as u64
                        || !observation_events.insert(fill.observation_event_id.as_str())
@@ -269,16 +300,52 @@ impl ManualExecutionReplay {
                                .into(),
                        );
                    }
+                    if fill.fee_observation_sequence == 0
+                        || fill.fee_observation_sequence > i64::MAX as u64
+                        || fill.fee_observed_at < fill.observed_at
+                        || fill.fee_observed_at > self.observation_cutoff
+                        || !fee_observations.insert((
+                            fill.fee_observation_event_id.as_str(),
+                            fill.fee_observation_sequence,
+                        ))
+                    {
+                        return Err("manual finalized fees require their own unique observation within the cutoff".into());
+                    }
+                    if (fill.fee_observation_event_id == fill.observation_event_id)
+                        != (fill.fee_observation_sequence == fill.observation_sequence)
+                        || (fill.fee_observation_event_id == fill.observation_event_id
+                            && fill.fee_observed_at != fill.observed_at)
+                    {
+                        return Err("manual fill and fee observation identities disagree".into());
+                    }
                    if !trades.insert((fill.trade_date, fill.trade_id.as_str()))
                        || fill.quantity == 0
                    {
                        return Err("duplicate manual trade or zero fill quantity".into());
                    }
+                    for (id, sequence) in [
+                        (&fill.observation_event_id, fill.observation_sequence),
+                        (
+                            &fill.fee_observation_event_id,
+                            fill.fee_observation_sequence,
+                        ),
+                    ] {
+                        if receipt_ids
+                            .insert(id, (&fill.trade_id, sequence))
+                            .is_some_and(|owner| owner != (&fill.trade_id, sequence))
+                            || receipt_sequences
+                                .insert(sequence, (&fill.trade_id, id))
+                                .is_some_and(|owner| owner != (&fill.trade_id, id))
+                        {
+                            return Err("manual observation identity is reused by a different trade or sequence".into());
+                        }
+                    }
                    if fill.executed_at.with_timezone(&shanghai).date_naive() != fill.trade_date
                        || fill.observed_at > self.observation_cutoff
-                        || fill.observed_at < order.submitted_at
+                        || fill.observed_at < order.order_created_at
+                        || fill.observed_at < action.confirmation_observed_at
                        || fill.observed_at < fill.executed_at
-                        || fill.executed_at > order.terminal_at
+                        || fill.executed_at > order.terminal_observed_at
                    {
                        return Err("manual fill execution/observation time is inconsistent".into());
                    }
@@ -297,18 +364,12 @@ impl ManualExecutionReplay {
                            fill.timestamp_precision.nanoseconds(),
                        ))
                        .ok_or("manual execution timestamp overflow")?;
-                    if fill.executed_at < order.submitted_at && order.submitted_at >= upper {
-                        return Err("manual fill predates its submitted order".into());
+                    let earliest = order.order_created_at.max(action.confirmation_observed_at);
+                    if fill.executed_at < earliest && earliest >= upper {
+                        return Err("manual fill predates its order or durable confirmation".into());
                    }
-                    if fill.price <= Decimal::ZERO
-                        || [fill.commission, fill.stamp_tax, fill.transfer_fee]
-                            .iter()
-                            .any(|fee| *fee < Decimal::ZERO)
-                    {
-                        return Err(
-                            "manual fill requires a positive price and complete nonnegative fees"
-                                .into(),
-                        );
+                    if fill.price <= Decimal::ZERO {
+                        return Err("manual fill requires a positive price".into());
                    }
                    fill.gross_amount()?
                        .checked_add(fill.total_fees()?)
@@ -367,15 +428,18 @@ pub struct ManualReplayApplication {
    pub observation_event_id: String,
    pub observation_sequence: u64,
    pub observed_at: DateTime<Utc>,
+    pub fee_observation_event_id: String,
+    pub fee_observed_at: DateTime<Utc>,
    pub executed_at: DateTime<Utc>,
    pub symbol: String,
    pub side: OrderSide,
    pub quantity: u32,
    pub quantity_after: u32,
    pub price: String,
-    pub commission: String,
-    pub stamp_tax: String,
-    pub transfer_fee: String,
+    pub commission: Option<String>,
+    pub stamp_tax: Option<String>,
+    pub transfer_fee: Option<String>,
+    pub source_total_fee: String,
    pub source_gross_amount: String,
    pub ledger_gross_amount: String,
    pub ledger_fees: String,
@@ -458,15 +522,18 @@ impl ManualReplayCursor {
                observation_event_id: fill.observation_event_id.clone(),
                observation_sequence: fill.observation_sequence,
                observed_at: fill.observed_at,
+                fee_observation_event_id: fill.fee_observation_event_id.clone(),
+                fee_observed_at: fill.fee_observed_at,
                executed_at: fill.executed_at,
                symbol: order.symbol.clone(),
                side: order.side,
                quantity: fill.quantity,
                quantity_after: applied.quantity_after,
                price: fill.price.to_string(),
-                commission: fill.commission.to_string(),
-                stamp_tax: fill.stamp_tax.to_string(),
-                transfer_fee: fill.transfer_fee.to_string(),
+                commission: fill.commission.map(|fee| fee.to_string()),
+                stamp_tax: fill.stamp_tax.map(|fee| fee.to_string()),
+                transfer_fee: fill.transfer_fee.map(|fee| fee.to_string()),
+                source_total_fee: fill.total_fee.to_string(),
                source_gross_amount: fill.gross_amount()?.to_string(),
                ledger_gross_amount: applied.gross.to_decimal_string(),
                ledger_fees: applied.fees.to_decimal_string(),