feat!: persist T-Bank data and synchronize reads

Store account membership, portfolio, operations, forecasts and market sources in SQLite.
Coalesce scoped refreshes, fence connection revisions, preserve complete financial
snapshots and stabilize operation period state.

BREAKING CHANGE: investment reads return data/meta resource envelopes and locally
persisted snapshots; consumers must use the matching OpenAPI contract and explicit
synchronization endpoints.

src/modules/investments/instruments/stocks/application/stock-market.service.ts

@@ -1,4 +1,9 @@
-import { Injectable, ServiceUnavailableException } from '@nestjs/common';
+import { CandleService } from '../../application/candle.service';
+import {
+  CatalogEnrichmentService,
+  type CatalogPayload,
+} from '../../application/catalog-enrichment.service';
+import { Injectable } from '@nestjs/common';
 import {
   decimalFromString,
   divide,
@@ -6,180 +11,101 @@ import {
   multiply,
   subtract,
 } from '../../../../../common/decimal';
-import { TbankClient } from '../../../../../integrations/tbank/tbank.api';
 import { decimal } from '../../../../../integrations/tbank/decimal';
+import { timestamp } from '../../application/instrument-market';
 import {
-  optional,
-  previousClose,
-  timestamp,
-} from '../../application/instrument-market';
-import {
-  StockCandlesDto,
   StockCandlesQueryDto,
   StockQuoteDto,
+  StockQuoteResourceDto,
 } from '../presentation/stock.dto';
 
-const dayMs = 86_400_000;
-
-import { StockCatalogService } from './stock-catalog.service';
-
-const PREVIOUS_CLOSE_LOOKBACK_DAYS = 20;
-const HALF_YEAR_MONTHS = 6;
-const YEAR_MONTHS = 12;
-const CANDLE_WINDOW_DAYS = 365;
 const CHANGE_PERCENT_DECIMAL_PLACES = 6;
 @Injectable()
 export class StockMarketService {
   constructor(
-    private readonly catalog: StockCatalogService,
-    private readonly tbank: TbankClient,
+    private readonly history: CandleService,
+    private readonly sources: CatalogEnrichmentService,
   ) {}
-  quote(userId: string, uid: string): Promise<StockQuoteDto> {
-    return this.catalog.cached(userId, `quote:${uid}`, async (token) => {
-      const share = await this.catalog.share(token, uid);
-      const unavailable: string[] = [];
-      const [last, tradingStatus] = await Promise.all([
-        optional(
-          () => this.tbank.getLastPrice(token, uid),
-          'price',
-          unavailable,
-        ),
-        optional(
-          () => this.tbank.getTradingStatus(token, uid),
-          'status',
-          unavailable,
-        ),
-      ]);
-      const priceAt = timestamp(last?.time);
-      const currency = share.currency?.toUpperCase();
-      const price =
-        last?.price && currency
-          ? { currency, value: formatDecimal(decimal(last.price)) }
-          : null;
-      const previous = priceAt
-        ? await optional(
-            async () => {
-              const end = new Date(priceAt);
-              return previousClose(
-                await this.tbank.getCandles(
-                  token,
-                  uid,
-                  new Date(
-                    end.valueOf() - PREVIOUS_CLOSE_LOOKBACK_DAYS * dayMs,
-                  ),
-                  end,
-                ),
-                priceAt,
-              );
-            },
-            'comparison',
-            unavailable,
-          )
-        : null;
-      const previousPrice =
-        previous?.close && currency
-          ? { currency, value: formatDecimal(decimal(previous.close)) }
-          : null;
-      const difference =
-        price && previousPrice
-          ? subtract(
-              decimalFromString(price.value),
-              decimalFromString(previousPrice.value),
-            )
-          : null;
-      return {
-        price,
-        priceAt,
-        tradingStatus,
-        previousCloseDate: timestamp(previous?.time)?.slice(0, 10) ?? null,
-        previousClose: previousPrice,
-        change:
-          difference && currency
-            ? { currency, value: formatDecimal(difference) }
-            : null,
-        changePercent:
-          difference &&
-          previousPrice &&
-          decimalFromString(previousPrice.value).value > 0n
-            ? formatDecimal(
-                divide(
-                  multiply(difference, decimalFromString('100')),
-                  decimalFromString(previousPrice.value),
-                  CHANGE_PERCENT_DECIMAL_PLACES,
-                ),
-              )
-            : null,
-        unavailable,
-        observedAt: new Date().toISOString(),
-      };
-    });
+  async quote(
+    userId: string,
+    uid: string,
+    observe = false,
+  ): Promise<StockQuoteResourceDto> {
+    const result = await this.sources.section(
+      userId,
+      'share',
+      uid,
+      'quote',
+      observe,
+    );
+    return {
+      data: result.values.instrument
+        ? stockQuote(result.values, result.unavailable, result.observedAt)
+        : null,
+      meta: result.meta,
+    };
   }
   candles(
     userId: string,
     uid: string,
     period: StockCandlesQueryDto['period'] = 'month',
-  ): Promise<StockCandlesDto> {
-    return this.catalog.cached(
+    observe = false,
+  ) {
+    return this.history.read(
       userId,
-      `candles:${uid}:${period}`,
-      async (token) => {
-        const share = await this.catalog.share(token, uid);
-        const historyFrom = timestamp(share.first_1dayCandleDate);
-        const to = new Date();
-        const from = new Date(to);
-        from.setUTCMonth(
-          from.getUTCMonth() -
-            (period === 'month'
-              ? 1
-              : period === 'halfYear'
-                ? HALF_YEAR_MONTHS
-                : YEAR_MONTHS),
-        );
-        if (period === 'all') {
-          if (!historyFrom)
-            throw new ServiceUnavailableException({
-              code: 'STOCK_HISTORY_START_UNAVAILABLE',
-            });
-          from.setTime(Date.parse(historyFrom));
-        } else if (historyFrom && Date.parse(historyFrom) > from.valueOf())
-          from.setTime(Date.parse(historyFrom));
-        const collected = new Map<string, StockCandlesDto['candles'][number]>();
-        // Conservative one-year windows also work with older deployed RPC limits.
-        for (let start = from.valueOf(); start < to.valueOf();) {
-          const end = Math.min(
-            start + CANDLE_WINDOW_DAYS * dayMs,
-            to.valueOf(),
-          );
-          for (const candle of await this.tbank.getCandles(
-            token,
-            uid,
-            new Date(start),
-            new Date(end),
-          )) {
-            const time = timestamp(candle.time);
-            if (
-              time &&
-              candle.close &&
-              Date.parse(time) >= from.valueOf() - dayMs &&
-              Date.parse(time) <= to.valueOf()
-            )
-              collected.set(time, {
-                time,
-                close: formatDecimal(decimal(candle.close)),
-                isComplete: candle.isComplete === true,
-              });
-          }
-          start = end;
-        }
-        return {
-          candles: [...collected.values()].sort((a, b) =>
-            a.time.localeCompare(b.time),
-          ),
-          currency: share.currency?.toUpperCase() || null,
-          historyFrom,
-          observedAt: new Date().toISOString(),
-        };
-      },
+      { uid, instrumentType: 'share', period },
+      observe,
     );
   }
 }
+
+export function stockQuote(
+  values: CatalogPayload,
+  unavailable: string[],
+  observedAt: string,
+): StockQuoteDto {
+  const { price: last, candle: previous, tradingStatus = null } = values;
+  const share = values.instrument;
+  const priceAt = timestamp(last?.time);
+  const currency = share?.currency?.toUpperCase();
+  const price =
+    last?.price && currency
+      ? { currency, value: formatDecimal(decimal(last.price)) }
+      : null;
+  const previousPrice =
+    previous?.close && currency
+      ? { currency, value: formatDecimal(decimal(previous.close)) }
+      : null;
+  const difference =
+    price && previousPrice
+      ? subtract(
+          decimalFromString(price.value),
+          decimalFromString(previousPrice.value),
+        )
+      : null;
+  return {
+    price,
+    priceAt,
+    tradingStatus,
+    previousCloseDate: timestamp(previous?.time)?.slice(0, 10) ?? null,
+    previousClose: previousPrice,
+    change:
+      difference && currency
+        ? { currency, value: formatDecimal(difference) }
+        : null,
+    changePercent:
+      difference &&
+      previousPrice &&
+      decimalFromString(previousPrice.value).value > 0n
+        ? formatDecimal(
+            divide(
+              multiply(difference, decimalFromString('100')),
+              decimalFromString(previousPrice.value),
+              CHANGE_PERCENT_DECIMAL_PLACES,
+            ),
+          )
+        : null,
+    unavailable,
+    observedAt,
+  };
+}