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.

test/portfolio-structure.e2e-spec.ts

@@ -4,40 +4,23 @@ import { Test } from '@nestjs/testing';
 import type { Server } from 'node:http';
 import request from 'supertest';
 import { AppModule } from '../src/app.module';
-import { TbankAccessService } from '../src/integrations/tbank/tbank-access.service';
+import { PrismaService } from '../src/prisma/prisma.service';
+import { setTimeout as delay } from 'node:timers/promises';
 import { TbankClient } from '../src/integrations/tbank/tbank.client';
 import { configureApp } from '../src/main';
-import { PortfolioService } from '../src/modules/investments/portfolio/application/portfolio.service';
 
 describe('Portfolio structure HTTP contract', () => {
   let app: INestApplication<Server>;
-  const context = {
-    token: 'fixture',
-    generation: 'fixture',
-    accounts: [
-      { id: 'a', name: 'A' },
-      { id: 'b', name: 'B' },
-    ],
-  };
   const tbank = {
+    validateToken: jest.fn().mockResolvedValue([
+      { id: 'a', name: 'A', type: 'ACCOUNT_TYPE_TINKOFF' },
+      { id: 'b', name: 'B', type: 'ACCOUNT_TYPE_TINKOFF' },
+    ]),
     getPortfolio: jest.fn(),
     getPositions: jest.fn(),
     getInstrumentByFigi: jest.fn().mockResolvedValue(null),
     getInstrumentByUid: jest.fn().mockResolvedValue(null),
   };
-  const access = {
-    withConnection: (_user: string, action: (value: unknown) => unknown) =>
-      action(context),
-    withSupportedAccounts: (
-      _user: string,
-      action: (value: unknown) => unknown,
-    ) => action(context),
-    withAccountForConnection: (
-      _context: unknown,
-      _id: string,
-      action: () => unknown,
-    ) => action(),
-  };
   const token = new JwtService().sign(
     { sub: 'structure-user', type: 'access' },
     { secret: process.env.JWT_SECRET },
@@ -45,17 +28,26 @@ describe('Portfolio structure HTTP contract', () => {
 
   beforeAll(async () => {
     const module = await Test.createTestingModule({ imports: [AppModule] })
-      .overrideProvider(TbankAccessService)
-      .useValue(access)
       .overrideProvider(TbankClient)
       .useValue(tbank)
       .compile();
     app = module.createNestApplication();
     configureApp(app);
     await app.init();
+    await app.get(PrismaService).user.create({
+      data: {
+        id: 'structure-user',
+        email: 'structure@example.invalid',
+        passwordHash: 'fixture',
+      },
+    });
   });
-  beforeEach(() => {
-    app.get(PortfolioService).invalidate('structure-user');
+  beforeEach(async () => {
+    await request(app.getHttpServer())
+      .put('/api/v1/tbank-connection')
+      .set('Authorization', `Bearer ${token}`)
+      .send({ token: 'fixture' })
+      .expect(200);
     tbank.getPortfolio.mockResolvedValue({
       positions: [
         {
@@ -70,15 +62,32 @@ describe('Portfolio structure HTTP contract', () => {
     });
   });
   afterAll(() => app.close());
+  async function load(id: string) {
+    await request(app.getHttpServer())
+      .get(`/api/v1/brokerage-accounts/${id}/portfolio`)
+      .set('Authorization', `Bearer ${token}`)
+      .expect(200);
+    for (let index = 0; index < 200; index += 1) {
+      if (
+        !(await app
+          .get(PrismaService)
+          .tbankSyncWork.count({ where: { state: 'running' } }))
+      )
+        return;
+      await delay(5);
+    }
+    throw new Error('Portfolio did not settle');
+  }
 
   it.each(['a', 'all'])(
     'serializes exact structure including cash for %s',
     async (id) => {
+      await load(id);
       const response = await request(app.getHttpServer())
         .get(`/api/v1/brokerage-accounts/${id}/portfolio`)
         .set('Authorization', `Bearer ${token}`)
         .expect(200);
-      expect(response.body).toMatchObject({
+      expect((response.body as { data: unknown }).data).toMatchObject({
         structure: {
           unvaluedCategories: [],
           currencies: [
@@ -111,11 +120,12 @@ describe('Portfolio structure HTTP contract', () => {
     tbank.getPortfolio.mockResolvedValue({
       positions: [{ instrumentType: 'bond', quantity: { units: 1 } }],
     });
+    await load('a');
     const response = await request(app.getHttpServer())
       .get('/api/v1/brokerage-accounts/a/portfolio')
       .set('Authorization', `Bearer ${token}`)
       .expect(200);
-    expect(response.body).toMatchObject({
+    expect((response.body as { data: unknown }).data).toMatchObject({
       structure: {
         unvaluedCategories: [{ type: 'BOND', count: 1 }],
         currencies: [
@@ -136,11 +146,12 @@ describe('Portfolio structure HTTP contract', () => {
     tbank.getPositions.mockImplementation((_token: string, id: string) => ({
       money: [{ currency: 'RUB', units: id === 'a' ? -10 : 40 }],
     }));
+    await load('all');
     const response = await request(app.getHttpServer())
       .get('/api/v1/brokerage-accounts/all/portfolio')
       .set('Authorization', `Bearer ${token}`)
       .expect(200);
-    expect(response.body).toMatchObject({
+    expect((response.body as { data: unknown }).data).toMatchObject({
       structure: {
         currencies: [
           {