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/portfolio/infrastructure/forecast.repository.ts

@@ -0,0 +1,154 @@
+import { Injectable } from '@nestjs/common';
+import { isDeepStrictEqual } from 'node:util';
+import type { Prisma } from '../../../../../generated/prisma/client';
+import { PrismaService } from '../../../../prisma/prisma.service';
+
+export type ForecastSourceVersion = {
+  instrumentUid: string;
+  source: string;
+  kind: string;
+  rangeKey: string;
+  dataRevision: number;
+  fetchedAt: Date;
+};
+const forecastSourceReadBatchSize = 100;
+
+@Injectable()
+export class ForecastRepository {
+  constructor(private readonly prisma: PrismaService) {}
+
+  resolve(input: {
+    userId: string;
+    revision: string;
+    membershipRevision: number;
+    scopeKey: string;
+    candidate?: object;
+    portfolioProjection: string;
+    portfolios: { accountId: string; dataRevision: number }[];
+    sources: ForecastSourceVersion[];
+    timestamps: { resourceKey: string; at: string }[];
+  }) {
+    return this.prisma.$transaction(async (tx) => {
+      const owner = { userId: input.userId, revision: input.revision };
+      if (input.candidate) {
+        const current = await tx.tbankConnection.updateMany({
+          where: {
+            ...owner,
+            membershipRevision: input.membershipRevision,
+            invalidToken: false,
+          },
+          data: { membershipRevision: { increment: 0 } },
+        });
+        if (!current.count) return null;
+      }
+      const connection = await tx.tbankConnection.findFirst({
+        where: {
+          ...owner,
+          membershipRevision: input.membershipRevision,
+          invalidToken: false,
+        },
+      });
+      if (!connection) return null;
+      const key = { ...owner, scopeKey: input.scopeKey };
+      const previous = await tx.tbankForecast.findUnique({
+        where: { userId_revision_scopeKey: key },
+      });
+      const fallback =
+        previous?.membershipRevision === input.membershipRevision
+          ? previous
+          : null;
+      if (!input.candidate) return fallback;
+      const portfolios = await tx.tbankPortfolio.findMany({
+        where: {
+          ...owner,
+          accountId: { in: input.portfolios.map((row) => row.accountId) },
+        },
+        select: { accountId: true, dataRevision: true },
+      });
+      if (
+        input.portfolios.some(
+          (expected) =>
+            !portfolios.some(
+              (row) =>
+                row.accountId === expected.accountId &&
+                row.dataRevision === expected.dataRevision,
+            ),
+        )
+      )
+        return fallback;
+      // Four identity parameters per source: stay below SQLite's parameter limit.
+      const sources: ForecastSourceVersion[] = [];
+      for (
+        let offset = 0;
+        offset < input.sources.length;
+        offset += forecastSourceReadBatchSize
+      )
+        sources.push(
+          ...(await tx.tbankInstrumentSource.findMany({
+            where: {
+              provider: 'tbank',
+              OR: input.sources
+                .slice(offset, offset + forecastSourceReadBatchSize)
+                .map(({ instrumentUid, source, kind, rangeKey }) => ({
+                  instrumentUid,
+                  source,
+                  kind,
+                  rangeKey,
+                })),
+            },
+            select: {
+              instrumentUid: true,
+              source: true,
+              kind: true,
+              rangeKey: true,
+              dataRevision: true,
+              fetchedAt: true,
+            },
+          })),
+        );
+      if (
+        input.sources.some(
+          (expected) =>
+            !sources.some(
+              (row) =>
+                row.instrumentUid === expected.instrumentUid &&
+                row.source === expected.source &&
+                row.kind === expected.kind &&
+                row.rangeKey === expected.rangeKey &&
+                row.dataRevision === expected.dataRevision &&
+                row.fetchedAt.valueOf() === expected.fetchedAt.valueOf(),
+            ),
+        )
+      )
+        return fallback;
+      const revisions = JSON.parse(
+        JSON.stringify({
+          portfolioProjection: input.portfolioProjection,
+          portfolios: input.portfolios,
+          sources: input.sources,
+        }),
+      ) as Prisma.InputJsonObject;
+      const timestamps = input.timestamps as Prisma.InputJsonArray;
+      if (
+        fallback &&
+        isDeepStrictEqual(fallback.dependencyRevisions, revisions) &&
+        isDeepStrictEqual(fallback.sourceTimestamps, timestamps)
+      )
+        return fallback;
+      const data = {
+        membershipRevision: input.membershipRevision,
+        payload: JSON.parse(
+          JSON.stringify(input.candidate),
+        ) as Prisma.InputJsonObject,
+        dependencyRevisions: revisions,
+        sourceTimestamps: timestamps,
+        calculatedAt: new Date(),
+      };
+      return tx.tbankForecast.upsert({
+        where: { userId_revision_scopeKey: key },
+        create: { ...key, ...data },
+        update: { ...data, dataRevision: { increment: 1 } },
+      });
+    });
+  }
+}

src/modules/investments/portfolio/infrastructure/portfolio.repository.ts

@@ -0,0 +1,157 @@
+import {
+  tbankSourceTtlMs,
+  tbankSourceNeedsRefresh,
+} from '../../../../integrations/tbank/tbank.api';
+import { Injectable } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
+import { PrismaService } from '../../../../prisma/prisma.service';
+import type { Prisma } from '../../../../../generated/prisma/client';
+import type { PortfolioDto } from '../presentation/portfolio.dto';
+
+type PortfolioAttempt = {
+  id: string;
+  attemptId: string;
+  userId: string;
+  revision: string;
+};
+export const portfolioFreshForMs = tbankSourceTtlMs.portfolio;
+
+@Injectable()
+export class PortfolioRepository {
+  constructor(private readonly prisma: PrismaService) {}
+
+  read(userId: string, revision: string) {
+    return this.prisma.$transaction((tx) =>
+      tx.tbankConnection.findUnique({
+        where: { userId_revision: { userId, revision }, invalidToken: false },
+        select: {
+          membershipAt: true,
+          membershipRevision: true,
+          accounts: {
+            orderBy: { upstreamOrder: 'asc' },
+            include: { portfolio: true },
+          },
+          work: {
+            where: {
+              OR: [
+                { scopeKey: 'membership' },
+                { scopeKey: { startsWith: 'portfolio:' } },
+              ],
+            },
+            select: { scopeKey: true, id: true, state: true, errorCode: true },
+          },
+        },
+      }),
+    );
+  }
+
+  reserve(
+    userId: string,
+    revision: string,
+    accountId: string,
+    processRunId: string,
+    active: ReadonlySet<string>,
+    force: boolean,
+  ) {
+    return this.prisma.$transaction(async (tx) => {
+      const current = await tx.tbankConnection.updateMany({
+        where: {
+          userId,
+          revision,
+          invalidToken: false,
+          accounts: { some: { accountId } },
+        },
+        data: { membershipRevision: { increment: 0 } },
+      });
+      if (!current.count) return null;
+      const snapshot = await tx.tbankPortfolio.findUnique({
+        where: { userId_revision_accountId: { userId, revision, accountId } },
+      });
+      if (
+        !force &&
+        snapshot &&
+        !tbankSourceNeedsRefresh('portfolio', snapshot.fetchedAt, new Date())
+      )
+        return null;
+      const scope = { userId, revision, scopeKey: portfolioWorkKey(accountId) };
+      const previous = await tx.tbankSyncWork.findUnique({
+        where: { userId_revision_scopeKey: scope },
+      });
+      if (
+        previous?.state === 'running' &&
+        previous.processRunId === processRunId &&
+        active.has(previous.attemptId)
+      )
+        return { work: previous, launch: false };
+      const data = {
+        state: 'running',
+        attemptId: randomUUID(),
+        processRunId,
+        priority: 1,
+        intent: { source: 'portfolio', accountId },
+        progress: {},
+        errorCode: null,
+      };
+      return {
+        work: await tx.tbankSyncWork.upsert({
+          where: { userId_revision_scopeKey: scope },
+          create: { ...scope, ...data, id: randomUUID() },
+          update: data,
+        }),
+        launch: true,
+      };
+    });
+  }
+
+  publish(
+    attempt: PortfolioAttempt,
+    accountId: string,
+    snapshot: PortfolioDto,
+  ) {
+    return this.prisma.$transaction(async (tx) => {
+      const claimed = await tx.tbankSyncWork.updateMany({
+        where: {
+          ...attempt,
+          state: 'running',
+          connection: {
+            invalidToken: false,
+            accounts: { some: { accountId } },
+          },
+        },
+        data: { state: 'complete', progress: {} },
+      });
+      if (!claimed.count) return false;
+      const scope = {
+        userId: attempt.userId,
+        revision: attempt.revision,
+        accountId,
+      };
+      const data = {
+        payload: JSON.parse(JSON.stringify(snapshot)) as Prisma.InputJsonObject,
+        fetchedAt: new Date(snapshot.lastSuccessfulAt),
+      };
+      await tx.tbankPortfolio.upsert({
+        where: { userId_revision_accountId: scope },
+        create: { ...scope, ...data },
+        update: { ...data, dataRevision: { increment: 1 } },
+      });
+      return true;
+    });
+  }
+
+  async fail(attempt: PortfolioAttempt) {
+    const result = await this.prisma.tbankSyncWork.updateMany({
+      where: {
+        ...attempt,
+        state: 'running',
+        connection: { invalidToken: false },
+      },
+      data: { state: 'failed', errorCode: 'TBANK_UNAVAILABLE' },
+    });
+    return result.count === 1;
+  }
+}
+
+export function portfolioWorkKey(accountId: string): string {
+  return `portfolio:${JSON.stringify(accountId)}`;
+}