fix(investments): align roles and date contracts

Identify income dependencies by role and document screen-specific dates.
Convert inclusive calendar days into half-open source ranges while
preserving operation timestamps and existing stored coverage.

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

@@ -4,6 +4,7 @@ import { MoneyDto } from '../../../common/money.dto';
 import { BrokerageOperationDto } from '../operations/operations.api';
 
 import {
+  InvestmentDependencyDto,
   InvestmentReadQueryDto,
   InvestmentResourceMetaDto,
 } from '../investment-resource.dto';
@@ -11,12 +12,20 @@ import {
 const dateOnly = /^\d{4}-\d{2}-\d{2}$/;
 
 export class IncomeAnalyticsQueryDto extends InvestmentReadQueryDto {
-  @ApiPropertyOptional({ format: 'date' })
+  @ApiPropertyOptional({
+    format: 'date',
+    description:
+      'Inclusive calendar date in Europe/Moscow. Supply both from/to or neither.',
+  })
   @IsOptional()
   @Matches(dateOnly)
   from?: string;
 
-  @ApiPropertyOptional({ format: 'date' })
+  @ApiPropertyOptional({
+    format: 'date',
+    description:
+      'Inclusive calendar date in Europe/Moscow, no later than today. Supply both from/to or neither.',
+  })
   @IsOptional()
   @Matches(dateOnly)
   to?: string;
@@ -152,9 +161,27 @@ export class IncomeSummaryResourceDto {
   declare meta: InvestmentResourceMetaDto;
 }
 
+const incomeDependencyRoles = ['selected', 'previous', 'year'] as const;
+
+export class IncomeDependencyDto extends InvestmentDependencyDto {
+  @ApiProperty({ enum: incomeDependencyRoles })
+  declare role: (typeof incomeDependencyRoles)[number];
+}
+
+export class IncomeAnalyticsMetaDto extends InvestmentResourceMetaDto {
+  @ApiProperty({
+    type: IncomeDependencyDto,
+    isArray: true,
+    required: true,
+    description:
+      'Dependencies identified by role, not array order or resourceKey. A missing role is unavailable.',
+  })
+  declare dependencies: IncomeDependencyDto[];
+}
+
 export class IncomeAnalyticsResourceDto {
   @ApiProperty({ type: IncomeAnalyticsDto, nullable: true })
   declare data: IncomeAnalyticsDto | null;
-  @ApiProperty({ type: InvestmentResourceMetaDto })
-  declare meta: InvestmentResourceMetaDto;
+  @ApiProperty({ type: IncomeAnalyticsMetaDto })
+  declare meta: IncomeAnalyticsMetaDto;
 }