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/income/income-analytics.controller.ts

@@ -4,10 +4,11 @@ import type { Request } from 'express';
 import { ApiProblemResponses } from '../../../common/decorators/api-safe-error-response.decorator';
 import { AccessPayload, JwtAuthGuard } from '../../auth/auth.api';
 import {
-  IncomeAnalyticsDto,
+  IncomeAnalyticsResourceDto,
   IncomeAnalyticsQueryDto,
-  IncomeSummaryDto,
+  IncomeSummaryResourceDto,
 } from './income-analytics.dto';
+import { InvestmentReadQueryDto } from '../investment-resource.dto';
 import { IncomeAnalyticsService } from './income-analytics.service';
 
 @ApiTags('brokerage-accounts')
@@ -19,31 +20,49 @@ export class IncomeAnalyticsController {
   constructor(private readonly income: IncomeAnalyticsService) {}
 
   @Get('all/income-summary')
-  @ApiOkResponse({ type: IncomeSummaryDto })
-  allSummary(@Req() request: Request & { user: AccessPayload }) {
-    return this.income.summary(request.user.sub, 'all');
+  @ApiOkResponse({ type: IncomeSummaryResourceDto })
+  allSummary(
+    @Req() request: Request & { user: AccessPayload },
+    @Query() query: InvestmentReadQueryDto,
+  ) {
+    return this.income.summary(
+      request.user.sub,
+      'all',
+      query.sync === 'observe',
+    );
   }
 
   @Get('all/income-analytics')
-  @ApiOkResponse({ type: IncomeAnalyticsDto })
+  @ApiOkResponse({ type: IncomeAnalyticsResourceDto })
   allAnalytics(
     @Req() request: Request & { user: AccessPayload },
     @Query() query: IncomeAnalyticsQueryDto,
   ) {
-    return this.income.analytics(request.user.sub, 'all', query.from, query.to);
+    return this.income.analytics(
+      request.user.sub,
+      'all',
+      query.from,
+      query.to,
+      query.sync === 'observe',
+    );
   }
 
   @Get(':accountId/income-summary')
-  @ApiOkResponse({ type: IncomeSummaryDto })
+  @ApiOkResponse({ type: IncomeSummaryResourceDto })
   summary(
     @Req() request: Request & { user: AccessPayload },
     @Param('accountId') accountId: string,
+    @Query() query: InvestmentReadQueryDto,
   ) {
-    return this.income.summary(request.user.sub, accountId);
+    return this.income.summary(
+      request.user.sub,
+      accountId,
+      query.sync === 'observe',
+    );
   }
 
   @Get(':accountId/income-analytics')
-  @ApiOkResponse({ type: IncomeAnalyticsDto })
+  @ApiOkResponse({ type: IncomeAnalyticsResourceDto })
   analytics(
     @Req() request: Request & { user: AccessPayload },
     @Param('accountId') accountId: string,
@@ -54,6 +73,7 @@ export class IncomeAnalyticsController {
       accountId,
       query.from,
       query.to,
+      query.sync === 'observe',
     );
   }
 }

src/modules/investments/income/income-analytics.dto.ts

@@ -3,9 +3,14 @@ import { IsOptional, Matches } from 'class-validator';
 import { MoneyDto } from '../../../common/money.dto';
 import { BrokerageOperationDto } from '../operations/operations.api';
 
+import {
+  InvestmentReadQueryDto,
+  InvestmentResourceMetaDto,
+} from '../investment-resource.dto';
+
 const dateOnly = /^\d{4}-\d{2}-\d{2}$/;
 
-export class IncomeAnalyticsQueryDto {
+export class IncomeAnalyticsQueryDto extends InvestmentReadQueryDto {
   @ApiPropertyOptional({ format: 'date' })
   @IsOptional()
   @Matches(dateOnly)
@@ -121,8 +126,8 @@ export class IncomeAnalyticsEntryDto extends BrokerageOperationDto {
 }
 
 export class IncomeAnalyticsDto extends IncomeSummaryDto {
-  @ApiProperty({ type: IncomeComparisonDto })
-  declare previous: IncomeComparisonDto;
+  @ApiProperty({ type: IncomeComparisonDto, nullable: true })
+  declare previous: IncomeComparisonDto | null;
 
   @ApiProperty({ type: IncomeComparisonDto, nullable: true })
   declare yearComparison: IncomeComparisonDto | null;
@@ -139,3 +144,17 @@ export class IncomeAnalyticsDto extends IncomeSummaryDto {
   @ApiProperty({ type: IncomeAnalyticsEntryDto, isArray: true })
   declare entries: IncomeAnalyticsEntryDto[];
 }
+
+export class IncomeSummaryResourceDto {
+  @ApiProperty({ type: IncomeSummaryDto, nullable: true })
+  declare data: IncomeSummaryDto | null;
+  @ApiProperty({ type: InvestmentResourceMetaDto })
+  declare meta: InvestmentResourceMetaDto;
+}
+
+export class IncomeAnalyticsResourceDto {
+  @ApiProperty({ type: IncomeAnalyticsDto, nullable: true })
+  declare data: IncomeAnalyticsDto | null;
+  @ApiProperty({ type: InvestmentResourceMetaDto })
+  declare meta: InvestmentResourceMetaDto;
+}

src/modules/investments/income/income-analytics.service.spec.ts

@@ -1,8 +1,13 @@
+jest.mock('../../../prisma/prisma.service', () => ({
+  PrismaService: class {},
+}));
 jest.mock('../operations/application/brokerage-operations.service', () => ({
   BrokerageOperationsService: class BrokerageOperationsService {},
 }));
 
+import assert from 'node:assert/strict';
 import { BrokerageOperationDto } from '../operations/presentation/brokerage-operation.dto';
+import { investmentResourceMeta } from '../investment-resource.mapper';
 import { IncomeAnalyticsService } from './income-analytics.service';
 
 describe('IncomeAnalyticsService', () => {
@@ -19,7 +24,10 @@ describe('IncomeAnalyticsService', () => {
         build: (opened?: Date) => unknown[],
       ) => {
         build(undefined);
-        return { pages: [[{ items }], [{ items: [] }], [{ items: [] }]] };
+        return [items, [], []].map((items, index) => ({
+          items,
+          meta: completeMeta(index),
+        }));
       },
     );
   }
@@ -57,13 +65,15 @@ describe('IncomeAnalyticsService', () => {
       };
       seed([payment]);
 
-      const result = await service.analytics(
+      const response = await service.analytics(
         'user',
         'account',
         '2026-01-01',
         '2026-01-31',
       );
 
+      const result = response.data;
+      assert(result);
       expect(result.entries).toEqual([{ ...payment, instrumentKey: key }]);
       expect(result.instruments).toEqual([
         expect.objectContaining({
@@ -92,13 +102,15 @@ describe('IncomeAnalyticsService', () => {
     ];
     seed(selected);
 
-    const result = await service.analytics(
+    const response = await service.analytics(
       'user',
       'account',
       '2026-01-01',
       '2026-01-31',
     );
 
+    const result = response.data;
+    assert(result);
     expect(result.entries).toEqual(
       selected.map((item) => ({
         ...item,
@@ -146,37 +158,28 @@ describe('IncomeAnalyticsService', () => {
         build: (opened?: Date) => unknown[],
       ) => {
         build(undefined);
-        return {
-          pages: [
-            [
-              {
-                items: [
-                  entry('coupon', 'OPERATION_TYPE_COUPON', '10.25', 'RUB'),
-                  entry('dividend', 'OPERATION_TYPE_DIVIDEND', '-2.5', 'RUB'),
-                  entry(
-                    'transfer',
-                    'OPERATION_TYPE_DIVIDEND_TRANSFER',
-                    '99',
-                    'RUB',
-                  ),
-                  entry('usd', 'OPERATION_TYPE_COUPON', '1', 'USD'),
-                ],
-              },
-            ],
-            [{ items: [] }],
-            [{ items: [] }],
+        return [
+          [
+            entry('coupon', 'OPERATION_TYPE_COUPON', '10.25', 'RUB'),
+            entry('dividend', 'OPERATION_TYPE_DIVIDEND', '-2.5', 'RUB'),
+            entry('transfer', 'OPERATION_TYPE_DIVIDEND_TRANSFER', '99', 'RUB'),
+            entry('usd', 'OPERATION_TYPE_COUPON', '1', 'USD'),
           ],
-        };
+          [],
+          [],
+        ].map((items, index) => ({ items, meta: completeMeta(index) }));
       },
     );
 
-    const result = await service.analytics(
+    const response = await service.analytics(
       'user',
       'account',
       '2026-01-01',
       '2026-01-31',
     );
 
+    const result = response.data;
+    assert(result);
     expect(result.totalsByCurrency).toEqual([
       expect.objectContaining({
         currency: 'RUB',
@@ -222,3 +225,14 @@ function entry(
     commission: null,
   };
 }
+
+function completeMeta(index: number) {
+  return investmentResourceMeta({
+    resourceKey: `period/${index}`,
+    dataRevision: '1',
+    availability: 'complete',
+    fetchedAt: new Date('2026-02-01Z'),
+    freshForMs: Infinity,
+    work: null,
+  });
+}

src/modules/investments/income/income-analytics.service.ts

@@ -1,3 +1,4 @@
+import assert from 'node:assert/strict';
 import { Injectable } from '@nestjs/common';
 import {
   add,
@@ -6,6 +7,11 @@ import {
   formatDecimal,
   subtract,
 } from '../../../common/decimal';
+import { investmentResourceMeta } from '../investment-resource.mapper';
+import {
+  IncomeAnalyticsResourceDto,
+  IncomeSummaryResourceDto,
+} from './income-analytics.dto';
 import { DateOnlyRange, moscowDate } from '../investment-calendar';
 import {
   BrokerageOperationDto,
@@ -13,7 +19,6 @@ import {
 } from '../operations/operations.api';
 
 import {
-  IncomeAnalyticsDto,
   IncomeAnalyticsEntryDto,
   IncomeComparisonDto,
   IncomeCurrencySummaryDto,
@@ -35,24 +40,32 @@ type Total = {
 export class IncomeAnalyticsService {
   constructor(private readonly operations: BrokerageOperationsService) {}
 
-  async summary(userId: string, accountId: string): Promise<IncomeSummaryDto> {
-    let plan: ReturnType<typeof planIncomePeriod> | undefined;
-    const collected = await this.operations.collectRanges(
+  async summary(
+    userId: string,
+    accountId: string,
+    observe = false,
+  ): Promise<IncomeSummaryResourceDto> {
+    let plan = planIncomePeriod(undefined, undefined);
+    const [selected] = await this.operations.collectRanges(
       userId,
       accountId,
       (openedAt) => {
-        const planned = planIncomePeriod(undefined, undefined, openedAt);
-        plan = planned;
-        return [planned.selected];
+        plan = planIncomePeriod(undefined, undefined, openedAt);
+        return [plan.selected];
       },
+      observe,
     );
-    if (!plan) throw new Error('Income period was not planned');
-    return summaryResponse(
-      accountId,
-      plan.selected,
-      qualifying(collected.pages[0].flatMap((page) => page.items)),
-      new Date().toISOString(),
-    );
+    if (selected.items === null) return { data: null, meta: selected.meta };
+    assert(selected.meta.lastSuccessfulAt);
+    return {
+      data: summaryResponse(
+        accountId,
+        plan.selected,
+        qualifying(selected.items),
+        selected.meta.lastSuccessfulAt,
+      ),
+      meta: selected.meta,
+    };
   }
 
   async analytics(
@@ -60,52 +73,80 @@ export class IncomeAnalyticsService {
     accountId: string,
     from: string | undefined,
     to: string | undefined,
-  ): Promise<IncomeAnalyticsDto> {
-    let plan: ReturnType<typeof planIncomePeriod> | undefined;
-    const collected = await this.operations.collectRanges(
+    observe = false,
+  ): Promise<IncomeAnalyticsResourceDto> {
+    let plan = planIncomePeriod(from, to);
+    const periods = await this.operations.collectRanges(
       userId,
       accountId,
       (openedAt) => {
-        const planned = planIncomePeriod(from, to, openedAt);
-        plan = planned;
+        plan = planIncomePeriod(from, to, openedAt);
         return [
-          planned.selected,
-          planned.previous,
-          ...(planned.yearAgo ? [planned.yearAgo] : []),
+          plan.selected,
+          plan.previous,
+          ...(plan.yearAgo ? [plan.yearAgo] : []),
         ];
       },
+      observe,
     );
-    if (!plan) throw new Error('Income period was not planned');
-    const selected = qualifying(
-      collected.pages[0].flatMap((page) => page.items),
-    ).map((entry) => ({
+    const [current, prior, year] = periods;
+    const dependencies = periods.map((period) => period.meta);
+    if (!plan.yearAgo)
+      dependencies.push({
+        ...investmentResourceMeta({
+          resourceKey: 'income/yearAgo', // gitleaks:allow public resource identifier
+          dataRevision: 'unavailable',
+          availability: 'missing',
+          fetchedAt: null,
+          freshForMs: 0,
+          work: null,
+          unavailableReason: 'CALENDAR_OR_ACCOUNT_HISTORY',
+        }),
+      });
+    const states = periods.map((period) => period.meta.sync);
+    const work =
+      states.find((state) => state.state === 'running') ??
+      states.find((state) => state.state === 'failed');
+    const meta = investmentResourceMeta({
+      resourceKey: `income/${accountId}/${plan.selected.from}/${plan.selected.to}`,
+      dataRevision: current.meta.dataRevision,
+      availability: current.meta.availability,
+      fetchedAt: current.meta.lastSuccessfulAt
+        ? new Date(current.meta.lastSuccessfulAt)
+        : null,
+      freshForMs: current.meta.freshness === 'fresh' ? Infinity : 0,
+      work: work?.id ? { ...work, id: work.id } : null,
+      coverage: current.meta.coverage,
+      dependencies,
+    });
+    if (current.items === null) return { data: null, meta };
+    assert(current.meta.lastSuccessfulAt);
+    const selected = qualifying(current.items).map((entry) => ({
       ...entry,
       instrumentKey: `${instrumentKey(entry)}:${entry.payment?.currency ?? ''}`,
     }));
-    const previous = qualifying(
-      collected.pages[1].flatMap((page) => page.items),
-    );
-    const yearAgo = plan.yearAgo
-      ? qualifying(collected.pages[2].flatMap((page) => page.items))
-      : null;
-    const calculatedAt = new Date().toISOString();
-    const base = summaryResponse(
-      accountId,
-      plan.selected,
-      selected,
-      calculatedAt,
-    );
     return {
-      ...base,
-      previous: comparison(selected, plan.previous, previous),
-      yearComparison:
-        plan.yearAgo && yearAgo
-          ? comparison(selected, plan.yearAgo, yearAgo)
-          : null,
-      bucketGranularity: plan.granularity,
-      buckets: buckets(plan.selected, plan.granularity, selected),
-      instruments: instruments(selected),
-      entries: selected,
+      data: {
+        ...summaryResponse(
+          accountId,
+          plan.selected,
+          selected,
+          current.meta.lastSuccessfulAt,
+        ),
+        previous:
+          prior.items === null
+            ? null
+            : comparison(selected, plan.previous, qualifying(prior.items)),
+        yearComparison:
+          plan.yearAgo && year?.items !== null && year
+            ? comparison(selected, plan.yearAgo, qualifying(year.items))
+            : null,
+        bucketGranularity: plan.granularity,
+        buckets: buckets(plan.selected, plan.granularity, selected),
+        instruments: instruments(selected),
+        entries: selected,
+      },
+      meta,
     };
   }
 }

src/modules/investments/income/income-read.api.ts

@@ -0,0 +1 @@
+export { IncomeAnalyticsService } from './income-analytics.service';

src/modules/investments/income/income.api.ts

@@ -0,0 +1 @@
+export { planIncomePeriod } from './income-period';

src/modules/investments/income/income.module.ts

@@ -8,5 +8,6 @@ import { IncomeAnalyticsService } from './income-analytics.service';
   imports: [AuthModule, OperationsModule],
   controllers: [IncomeAnalyticsController],
   providers: [IncomeAnalyticsService],
+  exports: [IncomeAnalyticsService],
 })
 export class IncomeModule {}