docs on the exchange rates proto file

common/proto/exchange_rates.proto

@@ -2,17 +2,55 @@ syntax = "proto3";
 
 package komp_ac.exchange_rates;
 
+// Selects WHICH DATE supplies the rate; this is independent of where the rate
+// comes from. These are not four user-facing choices: UNSPECIFIED is protobuf's
+// zero-value sentinel and is rejected when an explicit selection is supplied.
+//
+// User-facing mapping:
+// - "Automatic official rate" uses PREVIOUS_PUBLICATION for an ordinary
+//   transaction, or ON_OR_BEFORE_DATE for a financial statement.
+// - "Official rate from another date" uses SPECIFIC_PUBLICATION_DATE together
+//   with source OFFICIAL, a specific_rate_date, and an audit reason.
+// - A saved custom rate still uses one of these rules to determine which dated
+//   custom-rate record applies.
 enum ExchangeRateDateRule {
+  // Sentinel for an omitted date rule; never a selectable business option.
   EXCHANGE_RATE_DATE_RULE_UNSPECIFIED = 0;
+
+  // Latest valid publication strictly before the transaction date.
   EXCHANGE_RATE_DATE_RULE_PREVIOUS_PUBLICATION = 1;
+
+  // Latest valid publication on or before the financial-statement date.
   EXCHANGE_RATE_DATE_RULE_ON_OR_BEFORE_DATE = 2;
+
+  // An explicitly chosen publication date. Requires specific_rate_date and an
+  // audit reason; an official date must be a real provider publication date.
   EXCHANGE_RATE_DATE_RULE_SPECIFIC_PUBLICATION_DATE = 3;
 }
 
+// Selects WHERE THE RATE VALUE comes from; date selection is controlled by
+// ExchangeRateDateRule above. These are not four user-facing choices:
+// UNSPECIFIED is protobuf's zero-value sentinel and is rejected.
+//
+// Current user-facing mapping:
+// - "Automatic official rate" and "Official rate from another date" are both
+//   OFFICIAL; they differ only in ExchangeRateDateRule.
+// - "Saved custom rate" is SAVED_CUSTOM: a reusable row already persisted in
+//   the profile's custom_exchange_rates table.
+// - MANUAL is the current transaction-local, one-off quote path. If the product
+//   supports only persisted manual rates, this value and manual_foreign_units
+//   should be removed and SAVED_CUSTOM should be presented as "Manual rate".
 enum ExchangeRateSource {
+  // Sentinel for an omitted source; never a selectable business option.
   EXCHANGE_RATE_SOURCE_UNSPECIFIED = 0;
+
+  // An immutable observation imported from the configured official provider.
   EXCHANGE_RATE_SOURCE_OFFICIAL = 1;
+
+  // A reusable user-maintained quote stored in custom_exchange_rates.
   EXCHANGE_RATE_SOURCE_SAVED_CUSTOM = 2;
+
+  // A one-off quote carried only by this request and its audit evidence.
   EXCHANGE_RATE_SOURCE_MANUAL = 3;
 }
 

common/src/proto/komp_ac.exchange_rates.rs

@@ -213,12 +213,29 @@ pub struct AddProfileCurrencySourceRequest {
     #[prost(bool, tag = "4")]
     pub make_default: bool,
 }
+/// Selects WHICH DATE supplies the rate; this is independent of where the rate
+/// comes from. These are not four user-facing choices: UNSPECIFIED is protobuf's
+/// zero-value sentinel and is rejected when an explicit selection is supplied.
+///
+/// User-facing mapping:
+///
+/// * "Automatic official rate" uses PREVIOUS_PUBLICATION for an ordinary
+///   transaction, or ON_OR_BEFORE_DATE for a financial statement.
+/// * "Official rate from another date" uses SPECIFIC_PUBLICATION_DATE together
+///   with source OFFICIAL, a specific_rate_date, and an audit reason.
+/// * A saved custom rate still uses one of these rules to determine which dated
+///   custom-rate record applies.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
 #[repr(i32)]
 pub enum ExchangeRateDateRule {
+    /// Sentinel for an omitted date rule; never a selectable business option.
     Unspecified = 0,
+    /// Latest valid publication strictly before the transaction date.
     PreviousPublication = 1,
+    /// Latest valid publication on or before the financial-statement date.
     OnOrBeforeDate = 2,
+    /// An explicitly chosen publication date. Requires specific_rate_date and an
+    /// audit reason; an official date must be a real provider publication date.
     SpecificPublicationDate = 3,
 }
 impl ExchangeRateDateRule {
@@ -251,12 +268,29 @@ impl ExchangeRateDateRule {
         }
     }
 }
+/// Selects WHERE THE RATE VALUE comes from; date selection is controlled by
+/// ExchangeRateDateRule above. These are not four user-facing choices:
+/// UNSPECIFIED is protobuf's zero-value sentinel and is rejected.
+///
+/// Current user-facing mapping:
+///
+/// * "Automatic official rate" and "Official rate from another date" are both
+///   OFFICIAL; they differ only in ExchangeRateDateRule.
+/// * "Saved custom rate" is SAVED_CUSTOM: a reusable row already persisted in
+///   the profile's custom_exchange_rates table.
+/// * MANUAL is the current transaction-local, one-off quote path. If the product
+///   supports only persisted manual rates, this value and manual_foreign_units
+///   should be removed and SAVED_CUSTOM should be presented as "Manual rate".
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord, ::prost::Enumeration)]
 #[repr(i32)]
 pub enum ExchangeRateSource {
+    /// Sentinel for an omitted source; never a selectable business option.
     Unspecified = 0,
+    /// An immutable observation imported from the configured official provider.
     Official = 1,
+    /// A reusable user-maintained quote stored in custom_exchange_rates.
     SavedCustom = 2,
+    /// A one-off quote carried only by this request and its audit evidence.
     Manual = 3,
 }
 impl ExchangeRateSource {