@firela/api-types 0.0.0-canary.209966

package/src/generated/schemas.gen.ts

@@ -0,0 +1,4833 @@
+// This file is auto-generated by @hey-api/openapi-ts
+
+export const $CreateAccountDto = {
+  type: 'object',
+  properties: {
+    path: {
+      type: 'string',
+      description: 'Account path (hierarchical, colon-separated)',
+      example: 'Assets:CN:Bank:ICBC:Checking'
+    },
+    openDate: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Account open date',
+      example: '2024-01-01'
+    },
+    currencies: {
+      description: 'Allowed currencies (null = no restriction)',
+      example: ['CNY', 'USD'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    bookingMethod: {
+      type: 'string',
+      description: 'Booking method for cost basis',
+      enum: [
+        'FIFO',
+        'LIFO',
+        'HIFO',
+        'AVERAGE',
+        'STRICT',
+        'STRICT_WITH_SIZE',
+        'NONE'
+      ],
+      default: 'FIFO'
+    },
+    templatePath: {
+      type: 'string',
+      description: 'Reference to account-standards template path',
+      example: 'Assets:CN:Bank:ICBC:Checking'
+    },
+    isCustom: {
+      type: 'boolean',
+      description: 'Whether this is a custom (user-created) account',
+      default: false
+    },
+    i18nKey: {
+      type: 'string',
+      description: 'i18n key for display name (overrides template)',
+      example: 'account.custom.mybank'
+    },
+    icon: {
+      type: 'string',
+      description: 'Icon identifier (overrides template)',
+      example: 'bank-custom'
+    },
+    openMeta: {
+      type: 'object',
+      description: 'Additional metadata',
+      example: {
+        branch: 'Downtown',
+        accountNumber: '1234'
+      }
+    },
+    platformId: {
+      type: 'string',
+      description: 'Platform ID (references Platform.id)',
+      example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
+    }
+  },
+  required: ['path', 'openDate']
+} as const;
+
+export const $AccountResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Account UUID',
+      example: '550e8400-e29b-41d4-a716-446655440000'
+    },
+    path: {
+      type: 'string',
+      description: 'Account path (hierarchical, colon-separated)',
+      example: 'Assets:CN:Bank:ICBC:Checking'
+    },
+    type: {
+      type: 'string',
+      description: 'Account type (root segment)',
+      enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
+      example: 'Assets'
+    },
+    status: {
+      type: 'string',
+      description: 'Account status',
+      enum: ['OPEN', 'CLOSED', 'SUSPENDED'],
+      example: 'OPEN'
+    },
+    openDate: {
+      type: 'string',
+      description: 'Account open date',
+      example: '2024-01-01'
+    },
+    closeDate: {
+      type: 'string',
+      description: 'Account close date (if closed)',
+      example: '2024-12-31'
+    },
+    currencies: {
+      description: 'Allowed currencies (null = no restriction)',
+      example: ['CNY', 'USD'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    bookingMethod: {
+      type: 'string',
+      description: 'Booking method',
+      enum: [
+        'FIFO',
+        'LIFO',
+        'HIFO',
+        'AVERAGE',
+        'STRICT',
+        'STRICT_WITH_SIZE',
+        'NONE'
+      ],
+      example: 'FIFO'
+    },
+    templatePath: {
+      type: 'string',
+      description: 'Template path reference',
+      example: 'Assets:CN:Bank:ICBC:Checking'
+    },
+    isCustom: {
+      type: 'boolean',
+      description: 'Whether this is a custom (user-created) account',
+      example: false
+    },
+    i18nKey: {
+      type: 'string',
+      description: 'i18n key for display name',
+      example: 'account.assets.cn.bank.icbc.checking'
+    },
+    icon: {
+      type: 'string',
+      description: 'Icon identifier',
+      example: 'bank-icbc'
+    },
+    openMeta: {
+      type: 'object',
+      description: 'Account metadata',
+      example: {
+        branch: 'Downtown'
+      }
+    },
+    platformId: {
+      type: 'object',
+      description: 'Platform ID (null if unbound)',
+      example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2'
+    },
+    platform: {
+      type: 'object',
+      description: 'Platform details (populated if platformId is set)'
+    },
+    createdAt: {
+      type: 'string',
+      description: 'Created timestamp',
+      example: '2024-01-01T00:00:00.000Z'
+    },
+    updatedAt: {
+      type: 'string',
+      description: 'Updated timestamp',
+      example: '2024-01-01T00:00:00.000Z'
+    }
+  },
+  required: [
+    'id',
+    'path',
+    'type',
+    'status',
+    'openDate',
+    'bookingMethod',
+    'isCustom',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $AccountListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'Array of accounts',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of accounts matching the query',
+      example: 50
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $UpdateAccountDto = {
+  type: 'object',
+  properties: {
+    currencies: {
+      description: 'Allowed currencies (null = no restriction)',
+      example: ['CNY', 'USD'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    bookingMethod: {
+      type: 'string',
+      description: 'Booking method for cost basis',
+      enum: [
+        'FIFO',
+        'LIFO',
+        'HIFO',
+        'AVERAGE',
+        'STRICT',
+        'STRICT_WITH_SIZE',
+        'NONE'
+      ]
+    },
+    i18nKey: {
+      type: 'string',
+      description: 'i18n key for display name',
+      example: 'account.custom.mybank'
+    },
+    icon: {
+      type: 'string',
+      description: 'Icon identifier',
+      example: 'bank-custom'
+    },
+    openMeta: {
+      type: 'object',
+      description: 'Additional metadata (merged with existing)',
+      example: {
+        branch: 'Uptown'
+      }
+    },
+    platformId: {
+      type: 'object',
+      description:
+        'Platform ID (references Platform.id), null to clear association',
+      example: 'c98e5d4a-2f71-4a5a-bb3c-92c9f231d5e2',
+      nullable: true
+    }
+  }
+} as const;
+
+export const $CloseAccountDto = {
+  type: 'object',
+  properties: {
+    closeDate: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Account close date',
+      example: '2024-12-31'
+    },
+    closeMeta: {
+      type: 'object',
+      description: 'Close directive metadata',
+      example: {
+        reason: 'Account migrated to new bank'
+      }
+    }
+  },
+  required: ['closeDate']
+} as const;
+
+export const $ReopenAccountDto = {
+  type: 'object',
+  properties: {
+    reopenDate: {
+      format: 'date-time',
+      type: 'string',
+      description: 'New open date (optional)',
+      example: '2025-01-01'
+    }
+  }
+} as const;
+
+export const $CreatePostingDto = {
+  type: 'object',
+  properties: {
+    account: {
+      type: 'string',
+      description:
+        'Account name in Beancount format (must start with uppercase, colon-separated)',
+      example: 'Assets:Bank:Checking'
+    },
+    units: {
+      type: 'string',
+      description:
+        'Amount as decimal string (max 15 integer + 15 decimal digits). Can be omitted for interpolation, but currency must also be omitted.',
+      example: '100.50',
+      pattern: '^-?\\d{1,15}(\\.\\d{1,15})?$'
+    },
+    currency: {
+      type: 'string',
+      description:
+        'Currency/commodity code. Required if units is provided, must be omitted if units is omitted.',
+      example: 'USD',
+      maxLength: 20
+    },
+    meta: {
+      type: 'object',
+      description: 'Posting-level metadata',
+      example: {
+        'tax-lot': 'Q1-2024'
+      }
+    }
+  },
+  required: ['account']
+} as const;
+
+export const $CreateTransactionDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO 8601 format)',
+      example: '2024-11-28'
+    },
+    flag: {
+      type: 'string',
+      description: 'Transaction flag: * (cleared), ! (pending)',
+      enum: ['*', '!'],
+      example: '*'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name',
+      example: 'Whole Foods Market'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration/description',
+      example: 'Grocery shopping'
+    },
+    tags: {
+      description: 'Transaction tags (without # prefix)',
+      example: ['vacation', 'personal'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    links: {
+      description: 'Transaction links (without ^ prefix)',
+      example: ['invoice-123'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    postings: {
+      description:
+        'Transaction postings (minimum 1, typically 2 for double-entry)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CreatePostingDto'
+      }
+    },
+    meta: {
+      type: 'object',
+      description: 'Transaction-level metadata',
+      example: {
+        invoice: '12345'
+      }
+    },
+    idempotencyKey: {
+      type: 'string',
+      description:
+        'Unique key for idempotent transaction creation. If provided, duplicate requests with the same key will return the existing transaction.',
+      example: 'import-2024-01-15-batch-001',
+      maxLength: 128
+    },
+    autoCreateAccounts: {
+      type: 'boolean',
+      description:
+        'Auto-create accounts if not found. When true, missing accounts will be automatically created. When false (default for API), missing accounts will cause a validation error. Set to true for quick entry scenarios where you want to create accounts on-the-fly.',
+      default: true,
+      example: true
+    }
+  },
+  required: ['date', 'narration', 'postings']
+} as const;
+
+export const $PostingResponseDto = {
+  type: 'object',
+  properties: {
+    account: {
+      type: 'string',
+      description: 'Account name',
+      example: 'Assets:Bank:Checking'
+    },
+    units: {
+      type: 'string',
+      description: 'Amount (may be null if interpolated)',
+      example: '100.50'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency',
+      example: 'USD'
+    }
+  },
+  required: ['account']
+} as const;
+
+export const $RecurringSuggestionDto = {
+  type: 'object',
+  properties: {
+    shouldSuggest: {
+      type: 'boolean',
+      description: 'Whether to suggest creating a recurring rule',
+      example: true
+    },
+    suggestedFrequency: {
+      type: 'string',
+      description: 'Suggested frequency based on pattern analysis',
+      enum: [
+        'WEEKLY',
+        'BIWEEKLY',
+        'MONTHLY',
+        'BIMONTHLY',
+        'QUARTERLY',
+        'YEARLY',
+        'CUSTOM'
+      ],
+      example: 'MONTHLY'
+    },
+    confidence: {
+      type: 'number',
+      description: 'Confidence score (0-1)',
+      minimum: 0,
+      maximum: 1,
+      example: 0.75
+    },
+    similarCount: {
+      type: 'number',
+      description: 'Number of similar historical transactions found',
+      minimum: 1,
+      example: 3
+    },
+    averageAmount: {
+      type: 'number',
+      description: 'Average amount across similar transactions',
+      example: 299
+    },
+    suggestedExpectedDay: {
+      type: 'number',
+      description:
+        'Suggested expected day of month (1-28). Only provided when dates are consistent.',
+      minimum: 1,
+      maximum: 28,
+      example: 15
+    }
+  },
+  required: [
+    'shouldSuggest',
+    'suggestedFrequency',
+    'confidence',
+    'similarCount',
+    'averageAmount'
+  ]
+} as const;
+
+export const $TransactionResponseDto = {
+  type: 'object',
+  properties: {
+    transactionId: {
+      type: 'string',
+      description: 'Database transaction ID',
+      example: 'clh1234567890abcdef'
+    },
+    idempotencyKey: {
+      type: 'string',
+      description: 'Idempotency key if provided during creation'
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date',
+      example: '2024-11-28'
+    },
+    flag: {
+      type: 'string',
+      description: 'Transaction flag',
+      example: '*'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name',
+      example: 'Whole Foods Market'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration',
+      example: 'Grocery shopping'
+    },
+    postings: {
+      description: 'Transaction postings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/PostingResponseDto'
+      }
+    },
+    interpolated: {
+      type: 'boolean',
+      description:
+        'Whether interpolation was applied to balance the transaction',
+      example: false
+    },
+    booked: {
+      type: 'boolean',
+      description: 'Whether booking (cost resolution) was applied',
+      example: false
+    },
+    warnings: {
+      description: 'Non-blocking warnings from pipeline processing',
+      example: ['Posting amount precision truncated'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    createdAccountIds: {
+      description:
+        'Account IDs auto-created for this transaction (empty for API source)',
+      example: [],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    recurringSuggestion: {
+      description:
+        'Recurring rule creation suggestion. Only present when no existing rule matched and similar historical transactions were detected.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/RecurringSuggestionDto'
+        }
+      ]
+    }
+  },
+  required: [
+    'transactionId',
+    'date',
+    'narration',
+    'postings',
+    'interpolated',
+    'booked',
+    'createdAccountIds'
+  ]
+} as const;
+
+export const $ApiProblemResponseDto = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      description: 'A URI reference that identifies the problem type',
+      example: '/errors/resource-not-found'
+    },
+    title: {
+      type: 'string',
+      description: 'A short, human-readable summary of the problem',
+      example: 'Resource not found'
+    },
+    status: {
+      type: 'number',
+      description: 'The HTTP status code',
+      example: 404
+    },
+    detail: {
+      type: 'string',
+      description: 'A human-readable explanation of the problem',
+      example: 'The requested resource with ID uuid-123 does not exist'
+    },
+    instance: {
+      type: 'string',
+      description: 'A URI reference that identifies the specific occurrence',
+      example: '/api/v1/resources/uuid-123'
+    },
+    extensions: {
+      type: 'object',
+      description: 'Additional extension data',
+      example: {
+        resourceId: 'uuid-123',
+        operation: 'findById'
+      }
+    }
+  },
+  required: ['type', 'title', 'status', 'detail']
+} as const;
+
+export const $PostingDetailDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Posting ID',
+      example: 'clh1234567890abcdef'
+    },
+    accountId: {
+      type: 'string',
+      description: 'Account ID',
+      example: 'clh1234567890abcdef'
+    },
+    accountName: {
+      type: 'string',
+      description: 'Account name',
+      example: 'Assets:Bank:Checking'
+    },
+    units: {
+      type: 'string',
+      description: 'Amount (may be null if interpolated)',
+      example: '100.50'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency',
+      example: 'USD'
+    },
+    costAmount: {
+      type: 'string',
+      description: 'Cost amount',
+      example: '98.00'
+    },
+    costCurrency: {
+      type: 'string',
+      description: 'Cost currency',
+      example: 'USD'
+    },
+    costDate: {
+      type: 'string',
+      description: 'Cost date',
+      example: '2024-01-15'
+    },
+    priceAmount: {
+      type: 'string',
+      description: 'Price amount',
+      example: '1.02'
+    },
+    priceCurrency: {
+      type: 'string',
+      description: 'Price currency',
+      example: 'EUR'
+    },
+    flag: {
+      type: 'string',
+      description: 'Posting flag',
+      example: '*'
+    },
+    meta: {
+      type: 'object',
+      description: 'Posting metadata'
+    }
+  },
+  required: ['id', 'accountId', 'accountName']
+} as const;
+
+export const $TransactionDetailDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Transaction ID',
+      example: 'clh1234567890abcdef'
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date',
+      example: '2024-11-28'
+    },
+    flag: {
+      type: 'string',
+      description: 'Transaction flag',
+      enum: [
+        'CLEARED',
+        'PENDING',
+        'PADDING',
+        'SUMMARIZE',
+        'TRANSFER',
+        'CONVERSIONS'
+      ],
+      example: 'CLEARED'
+    },
+    customFlag: {
+      type: 'string',
+      description: 'Custom flag (if not using standard flags)',
+      example: 'R'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name',
+      example: 'Whole Foods Market'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration',
+      example: 'Grocery shopping'
+    },
+    tags: {
+      description: 'Transaction tags',
+      example: ['groceries'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    links: {
+      description: 'Transaction links',
+      example: ['invoice-2024-001'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    meta: {
+      type: 'object',
+      description: 'Transaction metadata'
+    },
+    status: {
+      type: 'string',
+      description: 'Transaction status',
+      enum: ['ACTIVE', 'VOIDED', 'SUPERSEDED'],
+      example: 'ACTIVE'
+    },
+    sourceType: {
+      type: 'string',
+      description: 'Source type (how the transaction was created)',
+      enum: ['NLP', 'CSV', 'OCR', 'API']
+    },
+    sourcePlatform: {
+      type: 'string',
+      description: 'Source platform (e.g., alipay, wechat)',
+      example: 'alipay'
+    },
+    postings: {
+      description: 'Transaction postings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/PostingDetailDto'
+      }
+    },
+    createdAt: {
+      type: 'string',
+      description: 'Created at timestamp',
+      example: '2024-11-28T10:30:00.000Z'
+    },
+    voidedAt: {
+      type: 'string',
+      description: 'Voided at timestamp (if voided)',
+      example: '2024-11-29T15:00:00.000Z'
+    },
+    voidedBy: {
+      type: 'string',
+      description: 'User ID who voided this transaction',
+      example: 'clh1234567890abcdef'
+    },
+    correctionReason: {
+      type: 'string',
+      description: 'Correction reason (if voided or superseded)',
+      example: 'Duplicate entry'
+    }
+  },
+  required: [
+    'id',
+    'date',
+    'narration',
+    'tags',
+    'links',
+    'status',
+    'postings',
+    'createdAt'
+  ]
+} as const;
+
+export const $TransactionListResponseDto = {
+  type: 'object',
+  properties: {
+    data: {
+      description: 'List of transactions',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/TransactionDetailDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total count of matching transactions',
+      example: 100
+    },
+    limit: {
+      type: 'number',
+      description: 'Number of items per page',
+      example: 20
+    },
+    offset: {
+      type: 'number',
+      description: 'Number of items skipped',
+      example: 0
+    }
+  },
+  required: ['data', 'total', 'limit', 'offset']
+} as const;
+
+export const $UpdateTransactionDto = {
+  type: 'object',
+  properties: {
+    flag: {
+      type: 'string',
+      description: 'Transaction flag (CLEARED, PENDING, etc.)',
+      enum: [
+        'CLEARED',
+        'PENDING',
+        'PADDING',
+        'SUMMARIZE',
+        'TRANSFER',
+        'CONVERSIONS'
+      ],
+      example: 'CLEARED'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name',
+      maxLength: 500,
+      example: 'Whole Foods Market'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration/description',
+      maxLength: 1000,
+      example: 'Weekly grocery shopping'
+    },
+    tags: {
+      description: 'Transaction tags',
+      maxItems: 50,
+      example: ['groceries', 'weekly'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    links: {
+      description: 'Transaction links',
+      maxItems: 50,
+      example: ['invoice-2024-001'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    meta: {
+      type: 'object',
+      description: 'Transaction metadata (JSON object)',
+      example: {
+        category: 'Food:Groceries',
+        reviewed: true
+      }
+    }
+  }
+} as const;
+
+export const $AccountStandardResponseDto = {
+  type: 'object',
+  properties: {
+    path: {
+      type: 'string',
+      description: 'Account path (hierarchical, colon-separated)',
+      example: 'Assets:CN:Bank:ICBC:Checking'
+    },
+    type: {
+      type: 'string',
+      description: 'Account type in Beancount hierarchy',
+      enum: ['Assets', 'Liabilities', 'Income', 'Expenses', 'Equity'],
+      example: 'Assets'
+    },
+    i18nKey: {
+      type: 'string',
+      description: 'i18n key for localized display name',
+      example: 'account.assets.cn.bank.icbc.checking'
+    },
+    description: {
+      type: 'string',
+      description: 'Account description',
+      example: 'ICBC checking account for daily transactions'
+    },
+    tags: {
+      description: 'Account tags for categorization',
+      example: ['bank', 'checking', 'primary'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    icon: {
+      type: 'string',
+      description: 'Icon identifier for UI display',
+      example: 'bank-icbc'
+    }
+  },
+  required: ['path', 'type']
+} as const;
+
+export const $AccountStandardListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'Array of account templates',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountStandardResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of account templates',
+      example: 150
+    },
+    region: {
+      type: 'string',
+      description: 'Region code',
+      example: 'CN'
+    }
+  },
+  required: ['items', 'total', 'region']
+} as const;
+
+export const $BalanceResponseDto = {
+  type: 'object',
+  properties: {
+    account: {
+      type: 'string',
+      description: 'Account name',
+      example: 'Assets:Bank:Checking'
+    },
+    balance: {
+      type: 'string',
+      description: 'Balance amount (decimal string for precision)',
+      example: '12345.67'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'USD'
+    },
+    date: {
+      type: 'string',
+      description: 'Date of the balance calculation (ISO 8601)',
+      example: '2024-12-31T00:00:00.000Z'
+    }
+  },
+  required: ['account', 'balance', 'currency', 'date']
+} as const;
+
+export const $MultiCurrencyBalanceResponseDto = {
+  type: 'object',
+  properties: {
+    account: {
+      type: 'string',
+      description: 'Account name',
+      example: 'Assets:Bank:Checking'
+    },
+    balances: {
+      type: 'object',
+      description: 'Balances by currency',
+      example: {
+        USD: '12345.67',
+        CNY: '100000.00'
+      }
+    },
+    date: {
+      type: 'string',
+      description: 'Date of the balance calculation (ISO 8601)',
+      example: '2024-12-31T00:00:00.000Z'
+    }
+  },
+  required: ['account', 'balances', 'date']
+} as const;
+
+export const $TransactionSummaryDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Transaction ID (null if transaction deleted)',
+      example: 'clh1234567890abcdef',
+      nullable: true
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date (YYYY-MM-DD)',
+      example: '2024-03-15'
+    },
+    amount: {
+      type: 'string',
+      description: 'Transaction amount (absolute value)',
+      example: '128.50'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'CNY'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee/Merchant name',
+      example: 'Starbucks'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration',
+      example: 'Coffee purchase'
+    },
+    accountName: {
+      type: 'string',
+      description: 'Source account name (first posting)',
+      example: 'Assets:Bank:Checking'
+    },
+    sourceType: {
+      type: 'string',
+      description: 'Source type (NLP, CSV, OCR, API)',
+      enum: ['NLP', 'CSV', 'OCR', 'API']
+    },
+    sourcePlatform: {
+      type: 'string',
+      description: 'Source platform (e.g., alipay, wechat)',
+      example: 'alipay'
+    }
+  },
+  required: ['date', 'amount', 'currency', 'narration']
+} as const;
+
+export const $ReviewSummaryDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Review item ID'
+    },
+    type: {
+      type: 'string',
+      description: 'Review type',
+      enum: [
+        'DUPLICATE',
+        'RULE_MATCH',
+        'PAYEE_MATCH',
+        'ACCOUNT_VALIDATION',
+        'PIPELINE_ERROR'
+      ]
+    },
+    status: {
+      type: 'string',
+      description: 'Review status',
+      enum: ['PENDING', 'RESOLVED', 'EXPIRED', 'CANCELLED']
+    },
+    confidence: {
+      type: 'number',
+      description: 'Confidence score (0-1)'
+    },
+    confidenceLevel: {
+      type: 'string',
+      description: 'Confidence level derived from score',
+      enum: ['HIGH', 'MEDIUM', 'LOW']
+    },
+    summary: {
+      type: 'string',
+      description: 'Human-readable summary of the review item'
+    },
+    matchReasons: {
+      description: 'Human-readable reasons for branching',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    sourceType: {
+      type: 'string',
+      description: 'Source type (NLP, CSV, OCR, API)'
+    },
+    sourcePlatform: {
+      type: 'string',
+      description: 'Source platform (e.g., alipay, wechat)'
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp'
+    },
+    transaction: {
+      description:
+        'Transaction summary for display (null if transaction deleted)',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/TransactionSummaryDto'
+        }
+      ]
+    },
+    amount: {
+      type: 'string',
+      description: 'Transaction amount (convenience field for mobile display)'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code (convenience field for mobile display)'
+    },
+    merchantName: {
+      type: 'string',
+      description: 'Payee/Merchant name (convenience field for mobile display)'
+    },
+    accountName: {
+      type: 'string',
+      description: 'Account name (convenience field for mobile display)'
+    },
+    transactionTime: {
+      type: 'string',
+      description:
+        'Transaction date/time (convenience field for mobile display)'
+    }
+  },
+  required: [
+    'id',
+    'type',
+    'status',
+    'confidence',
+    'confidenceLevel',
+    'summary',
+    'matchReasons',
+    'sourceType',
+    'createdAt'
+  ]
+} as const;
+
+export const $ReviewListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ReviewSummaryDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of items'
+    },
+    page: {
+      type: 'number',
+      description: 'Current page number'
+    },
+    limit: {
+      type: 'number',
+      description: 'Items per page'
+    },
+    hasMore: {
+      type: 'boolean',
+      description: 'Whether there are more pages'
+    }
+  },
+  required: ['items', 'total', 'page', 'limit', 'hasMore']
+} as const;
+
+export const $ReviewStatsDto = {
+  type: 'object',
+  properties: {
+    total: {
+      type: 'number',
+      description: 'Total pending reviews'
+    },
+    byType: {
+      type: 'object',
+      description: 'Count by type'
+    },
+    oldestPending: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Oldest pending review date'
+    }
+  },
+  required: ['total', 'byType']
+} as const;
+
+export const $DecisionOptionDto = {
+  type: 'object',
+  properties: {
+    value: {
+      type: 'string',
+      description: 'The action value to submit (e.g., UPGRADE_REPLACE, ACCEPT)'
+    },
+    labelKey: {
+      type: 'string',
+      description:
+        'i18n message key for display label (e.g., review.payee.accept.label)'
+    },
+    descriptionKey: {
+      type: 'string',
+      description: 'i18n message key for description'
+    },
+    recommended: {
+      type: 'boolean',
+      description: 'Whether this is the recommended option'
+    }
+  },
+  required: ['value', 'labelKey']
+} as const;
+
+export const $ReviewDetailDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Review item ID'
+    },
+    type: {
+      type: 'string',
+      description: 'Review type',
+      enum: [
+        'DUPLICATE',
+        'RULE_MATCH',
+        'PAYEE_MATCH',
+        'ACCOUNT_VALIDATION',
+        'PIPELINE_ERROR'
+      ]
+    },
+    status: {
+      type: 'string',
+      description: 'Review status',
+      enum: ['PENDING', 'RESOLVED', 'EXPIRED', 'CANCELLED']
+    },
+    confidence: {
+      type: 'number',
+      description: 'Confidence score (0-1)'
+    },
+    confidenceLevel: {
+      type: 'string',
+      description: 'Confidence level derived from score',
+      enum: ['HIGH', 'MEDIUM', 'LOW']
+    },
+    summary: {
+      type: 'string',
+      description: 'Human-readable summary of the review item'
+    },
+    matchReasons: {
+      description: 'Human-readable reasons for branching',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    sourceType: {
+      type: 'string',
+      description: 'Source type (NLP, CSV, OCR, API)'
+    },
+    sourcePlatform: {
+      type: 'string',
+      description: 'Source platform (e.g., alipay, wechat)'
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp'
+    },
+    transaction: {
+      description:
+        'Transaction summary for display (null if transaction deleted)',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/TransactionSummaryDto'
+        }
+      ]
+    },
+    amount: {
+      type: 'string',
+      description: 'Transaction amount (convenience field for mobile display)'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code (convenience field for mobile display)'
+    },
+    merchantName: {
+      type: 'string',
+      description: 'Payee/Merchant name (convenience field for mobile display)'
+    },
+    accountName: {
+      type: 'string',
+      description: 'Account name (convenience field for mobile display)'
+    },
+    transactionTime: {
+      type: 'string',
+      description:
+        'Transaction date/time (convenience field for mobile display)'
+    },
+    reviewData: {
+      type: 'object',
+      description:
+        'Review-type-specific data (JSONB). Structure varies by type: DUPLICATE: {newTransaction, existingTransaction, matchScore}, RULE_MATCH: {transaction, matchedRule, suggestedAccount}, PAYEE_MATCH: {originalPayee, suggestedPayee}, ACCOUNT_VALIDATION: {invalidAccount, suggestedCorrection, similarAccounts}, PIPELINE_ERROR: {errorType, errorMessage}'
+    },
+    decisionOptions: {
+      description: 'Available decision options',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/DecisionOptionDto'
+      }
+    },
+    transactionId: {
+      type: 'string',
+      description: 'Related transaction ID if applicable'
+    }
+  },
+  required: [
+    'id',
+    'type',
+    'status',
+    'confidence',
+    'confidenceLevel',
+    'summary',
+    'matchReasons',
+    'sourceType',
+    'createdAt',
+    'reviewData',
+    'decisionOptions'
+  ]
+} as const;
+
+export const $PayeeResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier (UUID)',
+      example: 'uuid-123-456'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID (owner of this payee mapping)',
+      example: 'user-123'
+    },
+    payee: {
+      type: 'string',
+      description: "User's original payee name (e.g., 'Starbucks', 'McDonald')",
+      example: 'Starbucks'
+    },
+    payeeProfileId: {
+      type: 'object',
+      description:
+        'Reference to global PayeeProfile (merchant info, i18n keys, categories)',
+      example: 'uuid-789',
+      nullable: true
+    },
+    customCategory: {
+      type: 'object',
+      description:
+        "User's custom category (overrides PayeeProfile category if set)",
+      example: 'Dining:Coffee',
+      nullable: true
+    },
+    customTags: {
+      description: "User's custom tags (e.g., ['favorite', 'work_meal'])",
+      example: ['favorite', 'work_meal'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    useCount: {
+      type: 'number',
+      description:
+        'Usage count (number of times this payee was used in transactions)',
+      example: 42
+    },
+    lastUsedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Last used timestamp',
+      example: '2024-11-20T10:00:00Z'
+    },
+    meta: {
+      type: 'object',
+      description: 'Extended metadata (location, notes, contact info, etc.)',
+      example: {
+        location: 'Zhongguancun',
+        note: 'Near subway station',
+        favorite: true
+      }
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Active status (inactive payees hidden from autocomplete)',
+      example: true
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp (first time this payee was used)',
+      example: '2024-01-01T10:00:00Z'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Last update timestamp',
+      example: '2024-11-20T10:00:00Z'
+    }
+  },
+  required: [
+    'id',
+    'userId',
+    'payee',
+    'customTags',
+    'useCount',
+    'lastUsedAt',
+    'meta',
+    'isActive',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $PayeeListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'List of payees',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/PayeeResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of payees',
+      example: 42
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $PayeeAutocompleteResponseDto = {
+  type: 'object',
+  properties: {
+    suggestions: {
+      description: 'List of matching payee names',
+      example: ['Starbucks', 'Starbucks Coffee', 'Starbucks Reserve'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: ['suggestions']
+} as const;
+
+export const $PayeeStatsResponseDto = {
+  type: 'object',
+  properties: {
+    payee: {
+      type: 'string',
+      description: 'Payee name',
+      example: 'Starbucks'
+    },
+    transactionCount: {
+      type: 'number',
+      description: 'Total transaction count',
+      example: 42
+    },
+    lastUsedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Last used timestamp',
+      example: '2024-11-20T10:00:00Z'
+    }
+  },
+  required: ['payee', 'transactionCount', 'lastUsedAt']
+} as const;
+
+export const $PayeeProfileResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier (UUID)',
+      example: '550e8400-e29b-41d4-a716-446655440000'
+    },
+    canonical: {
+      type: 'string',
+      description: 'Canonical payee name (unique, case-insensitive)',
+      example: 'Starbucks'
+    },
+    aliases: {
+      description: 'Multi-language aliases',
+      example: ['Starbucks Coffee', 'SBUX'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    i18nKey: {
+      type: 'object',
+      description: 'Translation key for i18n',
+      example: 'payee.starbucks',
+      nullable: true
+    },
+    category: {
+      type: 'string',
+      description: 'Payee category',
+      enum: [
+        'RESTAURANT',
+        'CAFE',
+        'FAST_FOOD',
+        'BAR',
+        'SUPERMARKET',
+        'CONVENIENCE_STORE',
+        'SHOPPING_MALL',
+        'ONLINE_SHOPPING',
+        'TAXI',
+        'RIDE_SHARING',
+        'PUBLIC_TRANSPORT',
+        'PARKING',
+        'GAS_STATION',
+        'UTILITIES',
+        'TELECOM',
+        'STREAMING',
+        'HEALTHCARE',
+        'EDUCATION',
+        'ENTERTAINMENT',
+        'SPORTS',
+        'TRAVEL',
+        'HOTEL',
+        'OTHER'
+      ],
+      example: 'CAFE'
+    },
+    subCategory: {
+      type: 'object',
+      description: 'Sub-category',
+      example: 'coffee_chain',
+      nullable: true
+    },
+    countries: {
+      description: 'Country codes where payee operates',
+      example: ['CN', 'US', 'JP'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    primaryCountry: {
+      type: 'object',
+      description: 'Primary operating country',
+      example: 'US',
+      nullable: true
+    },
+    keywords: {
+      description: 'Search keywords',
+      example: ['coffee', 'cafe'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    logoUrl: {
+      type: 'object',
+      description: 'Logo URL',
+      example: 'https://example.com/logo.png',
+      nullable: true
+    },
+    website: {
+      type: 'object',
+      description: 'Official website',
+      example: 'https://www.starbucks.com',
+      nullable: true
+    },
+    description: {
+      type: 'object',
+      description: 'Description',
+      example: 'Global coffeehouse chain',
+      nullable: true
+    },
+    meta: {
+      type: 'object',
+      description: 'Extended metadata'
+    },
+    dataSource: {
+      type: 'string',
+      description: 'Data source',
+      enum: ['MANUAL', 'IMPORT', 'API', 'CROWDSOURCED'],
+      example: 'MANUAL'
+    },
+    verifiedAt: {
+      type: 'object',
+      description: 'Verification timestamp (null if not verified)',
+      example: '2025-01-01T00:00:00.000Z',
+      nullable: true
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Whether the profile is active',
+      example: true
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp',
+      example: '2025-01-01T00:00:00.000Z'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Last update timestamp',
+      example: '2025-01-01T00:00:00.000Z'
+    }
+  },
+  required: [
+    'id',
+    'canonical',
+    'aliases',
+    'category',
+    'countries',
+    'keywords',
+    'meta',
+    'dataSource',
+    'isActive',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $PayeeProfileListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'List of payee profiles',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/PayeeProfileResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total count of matching records',
+      example: 100
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $CommodityResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Unique identifier',
+      example: 'uuid-123-456'
+    },
+    userId: {
+      type: 'object',
+      description: 'User ID (owner of the commodity)',
+      example: 'user-123',
+      nullable: true
+    },
+    symbol: {
+      type: 'string',
+      description: 'Commodity symbol (corresponds to Beancount currency field)',
+      example: 'AAPL'
+    },
+    date: {
+      type: 'string',
+      description:
+        'Commodity definition date (required per Beancount spec). Represents when this commodity was first defined in the accounting system.',
+      example: '2024-01-01',
+      format: 'date'
+    },
+    metadata: {
+      type: 'object',
+      description:
+        'Metadata (corresponds to Beancount meta field). Contains name, assetClass, precision, note, tags, etc.',
+      example: {
+        name: 'Apple Inc.',
+        assetClass: 'stock',
+        precision: 2,
+        note: 'Tech stock',
+        source: 'AUTO_CREATED'
+      }
+    },
+    symbolProfileId: {
+      type: 'object',
+      description:
+        'Reference to SymbolProfile (market data integration, SaaS feature)',
+      example: 'uuid-789',
+      nullable: true
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp',
+      example: '2024-11-03T10:00:00Z'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Last update timestamp',
+      example: '2024-11-03T10:00:00Z'
+    }
+  },
+  required: ['id', 'symbol', 'date', 'metadata', 'createdAt', 'updatedAt']
+} as const;
+
+export const $CommodityListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      description: 'List of commodities',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CommodityResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total number of commodities',
+      example: 42
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $RecurringRuleResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Rule ID'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID'
+    },
+    name: {
+      type: 'string',
+      description: 'Rule name'
+    },
+    icon: {
+      type: 'object',
+      description: 'Icon emoji'
+    },
+    frequency: {
+      type: 'string',
+      description: 'Recurring frequency'
+    },
+    expectedAmount: {
+      type: 'number',
+      description: 'Expected amount'
+    },
+    expectedDay: {
+      type: 'object',
+      description: 'Expected day of month'
+    },
+    customIntervalDays: {
+      type: 'object',
+      description: 'Custom interval in days'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code'
+    },
+    matchPayeePattern: {
+      type: 'object',
+      description: 'Payee matching pattern'
+    },
+    matchAmountTolerance: {
+      type: 'number',
+      description: 'Amount tolerance percentage'
+    },
+    defaultExpenseAccount: {
+      type: 'object',
+      description: 'Default expense account'
+    },
+    defaultPaymentAccount: {
+      type: 'object',
+      description: 'Default payment account'
+    },
+    defaultPayee: {
+      type: 'object',
+      description: 'Default payee'
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Whether rule is active'
+    },
+    startDate: {
+      type: 'string',
+      description: 'Rule start date (YYYY-MM-DD)'
+    },
+    endDate: {
+      type: 'object',
+      description: 'Rule end date (YYYY-MM-DD)'
+    },
+    autoCreate: {
+      type: 'boolean',
+      description: 'Auto-create transaction on expected date'
+    },
+    lastOccurrence: {
+      type: 'object',
+      description: 'Last matched occurrence date (YYYY-MM-DD)'
+    },
+    totalCount: {
+      type: 'number',
+      description: 'Total matched transactions count'
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Created at timestamp'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Updated at timestamp'
+    }
+  },
+  required: [
+    'id',
+    'userId',
+    'name',
+    'frequency',
+    'expectedAmount',
+    'currency',
+    'matchAmountTolerance',
+    'isActive',
+    'startDate',
+    'autoCreate',
+    'totalCount',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $RecurringRuleWithStatsResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Rule ID'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID'
+    },
+    name: {
+      type: 'string',
+      description: 'Rule name'
+    },
+    icon: {
+      type: 'object',
+      description: 'Icon emoji'
+    },
+    frequency: {
+      type: 'string',
+      description: 'Recurring frequency'
+    },
+    expectedAmount: {
+      type: 'number',
+      description: 'Expected amount'
+    },
+    expectedDay: {
+      type: 'object',
+      description: 'Expected day of month'
+    },
+    customIntervalDays: {
+      type: 'object',
+      description: 'Custom interval in days'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code'
+    },
+    matchPayeePattern: {
+      type: 'object',
+      description: 'Payee matching pattern'
+    },
+    matchAmountTolerance: {
+      type: 'number',
+      description: 'Amount tolerance percentage'
+    },
+    defaultExpenseAccount: {
+      type: 'object',
+      description: 'Default expense account'
+    },
+    defaultPaymentAccount: {
+      type: 'object',
+      description: 'Default payment account'
+    },
+    defaultPayee: {
+      type: 'object',
+      description: 'Default payee'
+    },
+    isActive: {
+      type: 'boolean',
+      description: 'Whether rule is active'
+    },
+    startDate: {
+      type: 'string',
+      description: 'Rule start date (YYYY-MM-DD)'
+    },
+    endDate: {
+      type: 'object',
+      description: 'Rule end date (YYYY-MM-DD)'
+    },
+    autoCreate: {
+      type: 'boolean',
+      description: 'Auto-create transaction on expected date'
+    },
+    lastOccurrence: {
+      type: 'object',
+      description: 'Last matched occurrence date (YYYY-MM-DD)'
+    },
+    totalCount: {
+      type: 'number',
+      description: 'Total matched transactions count'
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Created at timestamp'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Updated at timestamp'
+    },
+    pendingCount: {
+      type: 'number',
+      description: 'Number of pending expected transactions'
+    },
+    overdueCount: {
+      type: 'number',
+      description: 'Number of overdue expected transactions'
+    },
+    nextExpectedDate: {
+      type: 'object',
+      description: 'Next expected date (YYYY-MM-DD)'
+    },
+    totalAmount: {
+      type: 'number',
+      description: 'Total amount of all matched transactions'
+    },
+    averageAmount: {
+      type: 'number',
+      description: 'Average amount per transaction'
+    },
+    transactionCount: {
+      type: 'number',
+      description: 'Number of matched transactions'
+    },
+    firstDate: {
+      type: 'object',
+      description: 'First matched transaction date (YYYY-MM-DD)'
+    },
+    lastDate: {
+      type: 'object',
+      description: 'Last matched transaction date (YYYY-MM-DD)'
+    },
+    variance: {
+      type: 'number',
+      description: 'Amount variance (standard deviation squared)'
+    },
+    upcomingCount: {
+      type: 'number',
+      description: 'Number of upcoming expected transactions'
+    }
+  },
+  required: [
+    'id',
+    'userId',
+    'name',
+    'frequency',
+    'expectedAmount',
+    'currency',
+    'matchAmountTolerance',
+    'isActive',
+    'startDate',
+    'autoCreate',
+    'totalCount',
+    'createdAt',
+    'updatedAt',
+    'pendingCount',
+    'overdueCount',
+    'totalAmount',
+    'averageAmount',
+    'transactionCount',
+    'variance',
+    'upcomingCount'
+  ]
+} as const;
+
+export const $ExpectedTransactionRuleDto = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      description: 'Rule name'
+    },
+    icon: {
+      type: 'object',
+      description: 'Rule icon'
+    },
+    frequency: {
+      type: 'string',
+      description: 'Rule frequency'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code'
+    }
+  },
+  required: ['name', 'frequency', 'currency']
+} as const;
+
+export const $ExpectedTransactionResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Expected transaction ID'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID'
+    },
+    ruleId: {
+      type: 'string',
+      description: 'Associated rule ID'
+    },
+    expectedDate: {
+      type: 'string',
+      description: 'Expected date (YYYY-MM-DD)'
+    },
+    expectedAmount: {
+      type: 'number',
+      description: 'Expected amount'
+    },
+    status: {
+      type: 'string',
+      description: 'Status (PENDING, COMPLETED, SKIPPED)'
+    },
+    matchedTransactionId: {
+      type: 'object',
+      description: 'Matched transaction ID'
+    },
+    matchedAt: {
+      type: 'object',
+      description: 'Match timestamp (ISO 8601)'
+    },
+    matchConfidence: {
+      type: 'object',
+      description: 'Match confidence score (0-1)'
+    },
+    isOverdue: {
+      type: 'boolean',
+      description: 'Whether this expected transaction is overdue'
+    },
+    rule: {
+      description: 'Rule information',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ExpectedTransactionRuleDto'
+        }
+      ]
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Created at timestamp'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Updated at timestamp'
+    }
+  },
+  required: [
+    'id',
+    'userId',
+    'ruleId',
+    'expectedDate',
+    'expectedAmount',
+    'status',
+    'isOverdue',
+    'rule',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $ExpectedTransactionListResponseDto = {
+  type: 'object',
+  properties: {
+    items: {
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExpectedTransactionResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total count'
+    }
+  },
+  required: ['items', 'total']
+} as const;
+
+export const $ForecastItemDto = {
+  type: 'object',
+  properties: {
+    rule: {
+      type: 'string',
+      description: 'Rule name',
+      example: 'Rent'
+    },
+    ruleId: {
+      type: 'string',
+      description: 'Rule ID',
+      example: 'clx123...'
+    },
+    amount: {
+      type: 'number',
+      description: 'Expected amount',
+      example: 3000
+    },
+    date: {
+      type: 'string',
+      description: 'Expected date (YYYY-MM-DD)',
+      example: '2024-04-01'
+    },
+    icon: {
+      type: 'object',
+      description: 'Rule icon emoji',
+      example: '🏠',
+      nullable: true
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'CNY'
+    }
+  },
+  required: ['rule', 'ruleId', 'amount', 'date', 'icon', 'currency']
+} as const;
+
+export const $MonthlyForecastDto = {
+  type: 'object',
+  properties: {
+    month: {
+      type: 'string',
+      description: 'Month (YYYY-MM)',
+      example: '2024-04'
+    },
+    expectedOutflow: {
+      type: 'number',
+      description: 'Total expected outflow for the month',
+      example: 8500
+    },
+    itemCount: {
+      type: 'number',
+      description: 'Number of expected transactions',
+      example: 3
+    },
+    byCurrency: {
+      type: 'object',
+      description: 'Breakdown by currency',
+      example: {
+        CNY: 8500,
+        USD: 100
+      }
+    },
+    items: {
+      description: 'Individual forecast items',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ForecastItemDto'
+      }
+    }
+  },
+  required: ['month', 'expectedOutflow', 'itemCount', 'byCurrency', 'items']
+} as const;
+
+export const $ForecastResponseDto = {
+  type: 'object',
+  properties: {
+    forecast: {
+      description: 'Monthly forecast data',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/MonthlyForecastDto'
+      }
+    },
+    totalOutflow: {
+      type: 'number',
+      description: 'Total expected outflow across all months',
+      example: 25500
+    },
+    totalByCurrency: {
+      type: 'object',
+      description: 'Total by currency across all months',
+      example: {
+        CNY: 25500,
+        USD: 300
+      }
+    },
+    rulesCount: {
+      type: 'number',
+      description: 'Number of active recurring rules included',
+      example: 5
+    },
+    periodStart: {
+      type: 'string',
+      description: 'Forecast period start date',
+      example: '2024-04-01'
+    },
+    periodEnd: {
+      type: 'string',
+      description: 'Forecast period end date',
+      example: '2024-06-30'
+    }
+  },
+  required: [
+    'forecast',
+    'totalOutflow',
+    'totalByCurrency',
+    'rulesCount',
+    'periodStart',
+    'periodEnd'
+  ]
+} as const;
+
+export const $TransactionRuleResponseDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Rule ID'
+    },
+    name: {
+      type: 'string',
+      description: 'Rule name'
+    },
+    description: {
+      type: 'string',
+      description: 'Rule description'
+    },
+    narrationKeywords: {
+      description: 'Keywords to match in transaction narration',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    payeeKeywords: {
+      description: 'Keywords to match in payee name',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    categoryKeywords: {
+      description: 'Keywords to match in category',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    methodKeywords: {
+      description: 'Keywords to match in payment method',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    categoryAccount: {
+      type: 'string',
+      description: 'Destination account for categorization'
+    },
+    matchLogic: {
+      type: 'string',
+      description: 'Keyword matching logic',
+      enum: ['OR', 'AND'],
+      example: 'OR'
+    },
+    amountRange: {
+      type: 'object',
+      description: 'Amount range for matching',
+      example: {
+        min: 0,
+        max: 100
+      }
+    },
+    priority: {
+      type: 'number',
+      description: 'Rule priority (0-1000, higher = first match)',
+      example: 50
+    },
+    enabled: {
+      type: 'boolean',
+      description: 'Whether the rule is enabled'
+    },
+    learningSource: {
+      type: 'string',
+      description: 'Learning source: NLP, REVIEW_CENTER, or null for manual',
+      enum: ['NLP', 'REVIEW_CENTER'],
+      example: 'REVIEW_CENTER'
+    },
+    autoApplyEnabled: {
+      type: 'boolean',
+      description: 'Whether auto-apply is enabled for this rule'
+    },
+    confirmationCount: {
+      type: 'number',
+      description: 'Number of confirmations for NLP-learned rules',
+      example: 3
+    },
+    additionalTags: {
+      description: 'Additional tags',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    additionalMetadata: {
+      type: 'object',
+      description: 'Additional metadata',
+      example: {}
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Created timestamp'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Updated timestamp'
+    }
+  },
+  required: [
+    'id',
+    'name',
+    'narrationKeywords',
+    'payeeKeywords',
+    'categoryKeywords',
+    'methodKeywords',
+    'matchLogic',
+    'priority',
+    'enabled',
+    'autoApplyEnabled',
+    'confirmationCount',
+    'additionalTags',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $TransactionRuleListResponseDto = {
+  type: 'object',
+  properties: {
+    data: {
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/TransactionRuleResponseDto'
+      }
+    },
+    total: {
+      type: 'number',
+      description: 'Total count of rules'
+    },
+    limit: {
+      type: 'number',
+      description: 'Results per page'
+    },
+    offset: {
+      type: 'number',
+      description: 'Pagination offset'
+    }
+  },
+  required: ['data', 'total', 'limit', 'offset']
+} as const;
+
+export const $ValidateRuleDto = {
+  type: 'object',
+  properties: {
+    name: {
+      type: 'string',
+      minLength: 1,
+      maxLength: 100
+    },
+    description: {
+      type: 'string',
+      maxLength: 500
+    },
+    narrationKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      type: 'array'
+    },
+    payeeKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      type: 'array'
+    },
+    categoryKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      type: 'array'
+    },
+    methodKeywords: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 50,
+      description: 'Payment method keywords (e.g., HuaBei, YuEBao)',
+      type: 'array'
+    },
+    categoryAccount: {
+      type: 'string',
+      maxLength: 200,
+      description:
+        'Destination account for expenses/income (e.g., Expenses:Food:Coffee)'
+    },
+    matchLogic: {
+      type: 'string',
+      enum: ['OR', 'AND'],
+      default: 'OR'
+    },
+    amountMin: {
+      type: 'number',
+      minimum: 0,
+      description: 'Minimum transaction amount (inclusive)'
+    },
+    amountMax: {
+      type: 'number',
+      minimum: 0,
+      description: 'Maximum transaction amount (inclusive)'
+    },
+    priority: {
+      type: 'number',
+      default: 50,
+      minimum: 0,
+      maximum: 1000
+    },
+    additionalTags: {
+      items: {
+        type: 'array'
+      },
+      maxItems: 20,
+      type: 'array'
+    },
+    additionalMetadata: {
+      type: 'object'
+    },
+    upsertByPayee: {
+      type: 'boolean',
+      description:
+        'If true, update existing rule with matching payeeKeywords[0] instead of creating new rule'
+    }
+  },
+  required: ['name', 'matchLogic', 'priority']
+} as const;
+
+export const $ValidateRuleResponseDto = {
+  type: 'object',
+  properties: {
+    valid: {
+      type: 'boolean',
+      description: 'Whether the rule configuration is valid',
+      example: true
+    },
+    errors: {
+      description: 'List of validation errors (empty if valid)',
+      example: [],
+      items: {
+        type: 'array'
+      },
+      type: 'array'
+    },
+    warnings: {
+      description: 'List of validation warnings (non-blocking issues)',
+      example: [
+        'No account constraints specified - rule will match any account'
+      ],
+      items: {
+        type: 'array'
+      },
+      type: 'array'
+    }
+  },
+  required: ['valid', 'errors', 'warnings']
+} as const;
+
+export const $ExportRulesResponseDto = {
+  type: 'object',
+  properties: {
+    exportedAt: {
+      type: 'string',
+      description: 'Export timestamp'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID'
+    },
+    ruleCount: {
+      type: 'number',
+      description: 'Number of exported rules'
+    },
+    rules: {
+      type: 'array',
+      description: 'Exported rules'
+    }
+  },
+  required: ['exportedAt', 'userId', 'ruleCount', 'rules']
+} as const;
+
+export const $RuleStatisticsResponseDto = {
+  type: 'object',
+  properties: {
+    period: {
+      type: 'string',
+      description: 'Statistics time period',
+      enum: ['7d', '30d', '90d']
+    },
+    totalRules: {
+      type: 'number',
+      description: 'Total number of rules'
+    },
+    rulesWithMatches: {
+      type: 'number',
+      description: 'Number of rules with at least one match'
+    },
+    totalMatches: {
+      type: 'number',
+      description: 'Total number of matches across all rules'
+    },
+    averageConfidence: {
+      type: 'number',
+      description: 'Average confidence score across all matches',
+      example: 0.82
+    },
+    ruleStats: {
+      type: 'array',
+      description: 'Per-rule statistics',
+      items: {
+        type: 'object',
+        properties: {
+          ruleId: {
+            type: 'string'
+          },
+          ruleName: {
+            type: 'string'
+          },
+          matchCount: {
+            type: 'number'
+          },
+          averageConfidence: {
+            type: 'number'
+          }
+        }
+      }
+    }
+  },
+  required: [
+    'period',
+    'totalRules',
+    'rulesWithMatches',
+    'totalMatches',
+    'averageConfidence',
+    'ruleStats'
+  ]
+} as const;
+
+export const $TestRuleDto = {
+  type: 'object',
+  properties: {
+    narration: {
+      type: 'string',
+      minLength: 1,
+      maxLength: 500
+    },
+    payee: {
+      type: 'string',
+      maxLength: 200
+    },
+    categoryAccount: {
+      type: 'string',
+      maxLength: 200
+    },
+    amount: {
+      type: 'number'
+    },
+    currency: {
+      type: 'string',
+      maxLength: 10
+    }
+  },
+  required: ['narration']
+} as const;
+
+export const $TestRuleResponseDto = {
+  type: 'object',
+  properties: {
+    ruleId: {
+      type: 'string',
+      description: 'Rule ID that was tested'
+    },
+    matches: {
+      type: 'boolean',
+      description: 'Whether the rule matched the test data'
+    },
+    confidence: {
+      type: 'number',
+      description: 'Match confidence score (0-1)',
+      example: 0.85
+    },
+    matchDetails: {
+      type: 'object',
+      description: 'Details of which fields matched',
+      example: {
+        narration: true,
+        payee: false,
+        categoryAccount: false
+      }
+    }
+  },
+  required: ['ruleId', 'matches', 'confidence', 'matchDetails']
+} as const;
+
+export const $DeleteOwnUserDto = {
+  type: 'object',
+  properties: {
+    accessToken: {
+      type: 'string',
+      description: 'Access token for user verification',
+      example: 'abc123xyz'
+    }
+  },
+  required: ['accessToken']
+} as const;
+
+export const $SignupDto = {
+  type: 'object',
+  properties: {
+    turnstileToken: {
+      type: 'string',
+      description:
+        'Cloudflare Turnstile verification token (optional when Turnstile disabled)',
+      example: '0.abc123def456...'
+    }
+  }
+} as const;
+
+export const $UpdateUserSettingDto = {
+  type: 'object',
+  properties: {
+    secId: {
+      type: 'number',
+      description: 'Security ID'
+    },
+    annualInterestRate: {
+      type: 'number',
+      description: 'Annual interest rate',
+      example: 0.05
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'USD'
+    },
+    baseCurrency: {
+      type: 'string',
+      description: 'Base currency code',
+      example: 'USD'
+    },
+    benchmark: {
+      type: 'string',
+      description: 'Benchmark symbol',
+      example: 'SPY'
+    },
+    colorScheme: {
+      type: 'string',
+      description: 'Color scheme',
+      enum: ['DARK', 'LIGHT']
+    },
+    dateRange: {
+      type: 'string',
+      description: 'Date range filter',
+      example: '1y'
+    },
+    emergencyFund: {
+      type: 'number',
+      description: 'Emergency fund amount',
+      example: 10000
+    },
+    'filters.accounts': {
+      description: 'Account filter IDs',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    'filters.assetClasses': {
+      description: 'Asset class filters',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    'filters.dataSource': {
+      type: 'string',
+      description: 'Data source filter'
+    },
+    'filters.symbol': {
+      type: 'string',
+      description: 'Symbol filter'
+    },
+    'filters.tags': {
+      description: 'Tag filters',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    isExperimentalFeatures: {
+      type: 'boolean',
+      description: 'Enable experimental features'
+    },
+    isRestrictedView: {
+      type: 'boolean',
+      description: 'Enable restricted view mode'
+    },
+    language: {
+      type: 'string',
+      description: 'Language code',
+      example: 'en'
+    },
+    locale: {
+      type: 'string',
+      description: 'Locale code',
+      example: 'en-US'
+    },
+    projectedTotalAmount: {
+      type: 'number',
+      description: 'Projected total amount',
+      example: 1000000
+    },
+    retirementDate: {
+      type: 'string',
+      description: 'Retirement date in ISO 8601 format',
+      example: '2050-01-01'
+    },
+    savingsRate: {
+      type: 'number',
+      description: 'Savings rate percentage',
+      example: 0.2
+    },
+    viewMode: {
+      type: 'string',
+      description: 'View mode',
+      enum: ['DEFAULT', 'ZEN']
+    }
+  }
+} as const;
+
+export const $FileImportDto = {
+  type: 'object',
+  properties: {
+    file: {
+      type: 'string',
+      format: 'binary',
+      description: 'Bill file to import (CSV, PDF, OFX, etc.)',
+      example: 'alipay.csv'
+    }
+  },
+  required: ['file']
+} as const;
+
+export const $ImportErrorDto = {
+  type: 'object',
+  properties: {
+    index: {
+      type: 'number',
+      description: 'Index of failed transaction in the file',
+      example: 5
+    },
+    error: {
+      type: 'string',
+      description: 'Error message',
+      example: 'Transaction does not balance: -100 USD != 0'
+    }
+  },
+  required: ['index', 'error']
+} as const;
+
+export const $ReviewItemPreviewDto = {
+  type: 'object',
+  properties: {
+    index: {
+      type: 'number',
+      description: 'Index in the import batch (for tracking)',
+      example: 0
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO format)',
+      example: '2026-03-05'
+    },
+    amount: {
+      type: 'number',
+      description: 'Transaction amount (absolute value)',
+      example: 99
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'CNY'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration/description',
+      example: 'Restaurant expense'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name',
+      example: 'Restaurant ABC'
+    },
+    category: {
+      type: 'string',
+      description: 'Inferred category from rule matching',
+      example: 'food'
+    },
+    confidence: {
+      type: 'number',
+      description: 'Confidence score for the match (0-1)',
+      example: 0.85
+    },
+    branchType: {
+      type: 'string',
+      description: 'Type of branch requiring review',
+      enum: [
+        'DUPLICATE',
+        'PAYEE_MATCH',
+        'RULE_MATCH',
+        'ACCOUNT_VALIDATION',
+        'PIPELINE_ERROR'
+      ],
+      example: 'RULE_MATCH'
+    },
+    reasons: {
+      description: 'Human-readable reasons for requiring review',
+      example: ['Moderate confidence rule match', 'Multiple rules matched'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: ['index', 'date', 'narration']
+} as const;
+
+export const $ImportResultDto = {
+  type: 'object',
+  properties: {
+    imported: {
+      type: 'number',
+      description: 'Number of successfully imported transactions',
+      example: 45
+    },
+    failed: {
+      type: 'number',
+      description: 'Number of failed transactions',
+      example: 2
+    },
+    skipped: {
+      type: 'number',
+      description:
+        'Number of skipped transactions (high confidence duplicates, auto-skipped)',
+      example: 3
+    },
+    pendingReview: {
+      type: 'number',
+      description:
+        'Number of transactions pending review (medium confidence duplicates)',
+      example: 2
+    },
+    errors: {
+      description: 'Array of error details for failed transactions',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ImportErrorDto'
+      }
+    },
+    reviewItems: {
+      description:
+        'Array of transactions pending review with preview data. Contains essential information for displaying in the import preview UI.',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ReviewItemPreviewDto'
+      }
+    },
+    transactions: {
+      type: 'object',
+      description: 'Array of imported transactions (optional, for debugging)'
+    }
+  },
+  required: ['imported', 'failed', 'skipped', 'pendingReview', 'errors']
+} as const;
+
+export const $IdentifyResultDto = {
+  type: 'object',
+  properties: {
+    identified: {
+      type: 'boolean',
+      description: 'Whether the file was successfully identified',
+      example: true
+    },
+    importerName: {
+      type: 'string',
+      description: 'Name of the importer that can handle this file',
+      example: 'AlipayImporter'
+    },
+    importerId: {
+      type: 'string',
+      description: 'Unique identifier of the importer',
+      example: 'alipay'
+    },
+    account: {
+      type: 'string',
+      description: 'Default account used by this importer',
+      example: 'Assets:Alipay:Balance'
+    },
+    message: {
+      type: 'string',
+      description: 'Message when file cannot be identified',
+      example: 'No matching importer found'
+    }
+  },
+  required: ['identified']
+} as const;
+
+export const $MapperDefaultsDto = {
+  type: 'object',
+  properties: {
+    sourceAccount: {
+      type: 'string',
+      description: 'Source account for transactions (Beancount format)',
+      example: 'Assets:Alipay:Balance'
+    },
+    currency: {
+      type: 'string',
+      description: 'Default currency (ISO 4217 code)',
+      example: 'CNY'
+    },
+    expenseAccount: {
+      type: 'string',
+      description: 'Default expense account',
+      example: 'Expenses:Unknown'
+    },
+    incomeAccount: {
+      type: 'string',
+      description: 'Default income account',
+      example: 'Income:Unknown'
+    },
+    accountMapping: {
+      type: 'object',
+      description:
+        'Filename prefix to account mapping (for HK importers). Maps filename prefix to Beancount account path.',
+      example: {
+        One: 'Assets:HSBC:One',
+        PULSE: 'Liabilities:CreditCards:HSBC:Pulse'
+      }
+    },
+    useCnh: {
+      type: 'boolean',
+      description:
+        'Convert CNY to CNH (offshore RMB) (for HK importers). Default: false.',
+      example: false
+    },
+    methodAccountMapping: {
+      type: 'object',
+      description:
+        'Payment method to source account mapping. Maps payment method keywords to Beancount account paths. Used by Alipay/WeChat importers to determine sourceAccount based on payment method (e.g., HuaBei, CreditCard).',
+      example: {
+        HuaBei: 'Liabilities:Alipay:Huabei',
+        CreditCard: 'Liabilities:CreditCard'
+      }
+    }
+  },
+  required: ['sourceAccount', 'currency']
+} as const;
+
+export const $ImporterConfigDataDto = {
+  type: 'object',
+  properties: {
+    defaults: {
+      description: 'Mapper defaults configuration',
+      allOf: [
+        {
+          $ref: '#/components/schemas/MapperDefaultsDto'
+        }
+      ]
+    }
+  },
+  required: ['defaults']
+} as const;
+
+export const $VersionedConfigDto = {
+  type: 'object',
+  properties: {
+    version: {
+      type: 'string',
+      description: 'Configuration version (semver)',
+      example: '1.0.0'
+    },
+    schema: {
+      type: 'string',
+      description: 'Configuration schema identifier',
+      example: 'importer-config-v1'
+    },
+    data: {
+      description: 'Configuration data',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ImporterConfigDataDto'
+        }
+      ]
+    }
+  },
+  required: ['version', 'schema', 'data']
+} as const;
+
+export const $ImporterConfigDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Configuration ID',
+      example: 'clx1234567890'
+    },
+    userId: {
+      type: 'string',
+      description: 'User ID',
+      example: 'user-abc-123'
+    },
+    importerId: {
+      type: 'string',
+      description: 'Importer identifier',
+      example: 'alipay',
+      enum: [
+        'alipay',
+        'alipay-web',
+        'alipay-yuebao',
+        'wechat',
+        'wechat-xlsx',
+        'boc',
+        'boc-credit',
+        'ccb',
+        'cmb',
+        'cmbc',
+        'cmbc-credit',
+        'icbc',
+        'icbc-credit',
+        'hsbc-hk'
+      ]
+    },
+    version: {
+      type: 'string',
+      description: 'Configuration version (semver)',
+      example: '1.0.0'
+    },
+    schema: {
+      type: 'string',
+      description: 'Configuration schema identifier',
+      example: 'importer-config-v1'
+    },
+    config: {
+      description: 'Configuration data (validated against Zod schema)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/VersionedConfigDto'
+        }
+      ]
+    },
+    createdAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Creation timestamp',
+      example: '2025-01-27T10:00:00Z'
+    },
+    updatedAt: {
+      format: 'date-time',
+      type: 'string',
+      description: 'Last update timestamp',
+      example: '2025-01-27T10:00:00Z'
+    }
+  },
+  required: [
+    'id',
+    'userId',
+    'importerId',
+    'version',
+    'schema',
+    'config',
+    'createdAt',
+    'updatedAt'
+  ]
+} as const;
+
+export const $ProviderSyncConfigDto = {
+  type: 'object',
+  properties: {
+    sourceAccount: {
+      type: 'string',
+      description: 'Source account for the first posting',
+      example: 'Assets:Bank:Chase'
+    },
+    defaultCurrency: {
+      type: 'string',
+      description: 'Default currency for transactions',
+      example: 'USD'
+    },
+    defaultExpenseAccount: {
+      type: 'string',
+      description: 'Default expense account for the second posting',
+      example: 'Expenses:Unknown'
+    },
+    defaultIncomeAccount: {
+      type: 'string',
+      description: 'Default income account for the second posting',
+      example: 'Income:Unknown'
+    },
+    filterPending: {
+      type: 'boolean',
+      description: 'Filter pending transactions',
+      default: true
+    }
+  },
+  required: [
+    'sourceAccount',
+    'defaultCurrency',
+    'defaultExpenseAccount',
+    'defaultIncomeAccount'
+  ]
+} as const;
+
+export const $ProviderSyncDto = {
+  type: 'object',
+  properties: {
+    provider: {
+      type: 'string',
+      description:
+        'Provider name (already in URL path, optional here for reference)',
+      example: 'plaid'
+    },
+    syncId: {
+      type: 'string',
+      description: 'Unique sync identifier for idempotency',
+      example: 'sync-12345'
+    },
+    config: {
+      description: 'Provider sync configuration',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ProviderSyncConfigDto'
+        }
+      ]
+    },
+    transactions: {
+      type: 'array',
+      description: 'Raw transactions from provider',
+      example: [
+        {
+          transaction_id: 'txn-001',
+          amount: 50,
+          iso_currency_code: 'USD',
+          date: '2024-01-15',
+          merchant_name: 'Starbucks',
+          name: 'STARBUCKS STORE 12345',
+          pending: false,
+          account_id: 'acc-001'
+        }
+      ]
+    }
+  },
+  required: ['config', 'transactions']
+} as const;
+
+export const $ProviderSyncResponseDto = {
+  type: 'object',
+  properties: {
+    imported: {
+      type: 'number',
+      description: 'Number of transactions successfully imported',
+      example: 10
+    },
+    skipped: {
+      type: 'number',
+      description: 'Number of transactions skipped (duplicates)',
+      example: 2
+    },
+    pendingReview: {
+      type: 'number',
+      description: 'Number of transactions pending review',
+      example: 3
+    },
+    failed: {
+      type: 'number',
+      description: 'Number of transactions that failed to import',
+      example: 0
+    },
+    importedTransactionIds: {
+      description: 'IDs of successfully imported transactions',
+      example: ['txn-001', 'txn-002'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    reviewItemIds: {
+      description: 'IDs of review items created for branched transactions',
+      example: ['review-001', 'review-002'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: ['imported', 'skipped', 'pendingReview', 'failed']
+} as const;
+
+export const $SupportedProvidersResponseDto = {
+  type: 'object',
+  properties: {
+    providers: {
+      description: 'List of supported provider names',
+      example: [
+        'plaid',
+        'teller',
+        'truelayer',
+        'gocardless',
+        'simplefin',
+        'yodlee',
+        'beancount-direct'
+      ],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: ['providers']
+} as const;
+
+export const $ProcessNlpDto = {
+  type: 'object',
+  properties: {
+    message: {
+      type: 'string',
+      description: 'Natural language text describing a transaction (Chinese)',
+      example: 'yesterday Starbucks spent 35 yuan',
+      maxLength: 500
+    },
+    sessionId: {
+      type: 'string',
+      description:
+        'Session ID for multi-turn conversation (auto-generated if not provided)',
+      example: 'session_abc123'
+    }
+  },
+  required: ['message']
+} as const;
+
+export const $NlpTransactionInfoDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Transaction ID'
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO format)'
+    },
+    amount: {
+      type: 'number',
+      description: 'Transaction amount'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration'
+    },
+    warning: {
+      type: 'string',
+      description:
+        'Warning message for special transaction scenarios (e.g., cross-currency settlement)',
+      example: '此交易使用USD账户结算。如需记录CNY支出，请创建货币转换交易。'
+    }
+  },
+  required: ['id', 'date', 'amount', 'currency']
+} as const;
+
+export const $NlpParsedDataDto = {
+  type: 'object',
+  properties: {
+    amount: {
+      type: 'number',
+      description: 'Extracted amount'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      default: 'CNY'
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO format)'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration'
+    },
+    category: {
+      type: 'string',
+      description: 'Category'
+    },
+    incomeType: {
+      type: 'string',
+      description: 'Income type (e.g., Salary, Bonus, Dividend, Interest)',
+      example: 'Salary'
+    },
+    incomeSource: {
+      type: 'string',
+      description: 'Income source (e.g., company name)',
+      example: 'Anthropic Inc.'
+    },
+    symbol: {
+      type: 'string',
+      description: 'Security symbol code (e.g., 600519, AAPL)',
+      example: '600519'
+    },
+    quantity: {
+      type: 'number',
+      description: 'Quantity of shares/units',
+      example: 100
+    },
+    price: {
+      type: 'number',
+      description: 'Unit price per share/unit',
+      example: 1900
+    },
+    investmentAction: {
+      type: 'string',
+      description: 'Investment action',
+      enum: ['buy', 'sell'],
+      example: 'buy'
+    },
+    paymentSource: {
+      type: 'string',
+      description: 'Payment source: asset (default) or liability (credit card)',
+      enum: ['asset', 'liability'],
+      example: 'asset'
+    },
+    liabilityHint: {
+      type: 'string',
+      description: 'Liability account hint (CreditCard/Huabei/Baitiao)',
+      example: 'CreditCard'
+    },
+    warning: {
+      type: 'string',
+      description:
+        'Warning message for special scenarios (e.g., cross-currency settlement)',
+      example: '此交易使用USD账户结算。如需记录CNY支出，请创建货币转换交易。'
+    }
+  }
+} as const;
+
+export const $NlpSourceTransactionDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO format)'
+    },
+    amount: {
+      type: 'string',
+      description: 'Amount as string'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration'
+    }
+  },
+  required: ['date', 'amount', 'currency', 'narration']
+} as const;
+
+export const $NlpTargetTransactionDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Existing transaction ID'
+    },
+    date: {
+      type: 'string',
+      description: 'Transaction date (ISO format)'
+    },
+    amount: {
+      type: 'string',
+      description: 'Amount as string'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code'
+    },
+    payee: {
+      type: 'string',
+      description: 'Payee name'
+    },
+    narration: {
+      type: 'string',
+      description: 'Transaction narration'
+    }
+  },
+  required: ['id', 'date', 'amount', 'currency', 'narration']
+} as const;
+
+export const $NlpSimilarityDto = {
+  type: 'object',
+  properties: {
+    dateMatch: {
+      type: 'boolean',
+      description: 'Whether dates match'
+    },
+    dateDiff: {
+      type: 'number',
+      description: 'Date difference in days'
+    },
+    amountMatch: {
+      type: 'boolean',
+      description: 'Whether amounts match'
+    },
+    amountDiff: {
+      type: 'string',
+      description: 'Amount difference as decimal string'
+    },
+    payeeMatch: {
+      type: 'boolean',
+      description: 'Whether payees match'
+    },
+    payeeSimilarity: {
+      type: 'number',
+      description: 'Payee similarity score (0-1)'
+    },
+    accountOverlap: {
+      type: 'number',
+      description: 'Account overlap score (0-1)'
+    }
+  },
+  required: [
+    'dateMatch',
+    'dateDiff',
+    'amountMatch',
+    'amountDiff',
+    'payeeMatch',
+    'payeeSimilarity',
+    'accountOverlap'
+  ]
+} as const;
+
+export const $NlpDuplicateConfirmationDataDto = {
+  type: 'object',
+  properties: {
+    confidence: {
+      type: 'number',
+      description: 'Duplicate detection confidence score (0.5-0.89)',
+      example: 0.85
+    },
+    sourceTransaction: {
+      description:
+        'Source transaction summary (the new transaction being entered)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSourceTransactionDto'
+        }
+      ]
+    },
+    targetTransaction: {
+      description: 'Target transaction summary (existing potential duplicate)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpTargetTransactionDto'
+        }
+      ]
+    },
+    similarity: {
+      description: 'Detailed similarity information',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSimilarityDto'
+        }
+      ]
+    },
+    reasons: {
+      description: 'Human-readable reasons for duplicate detection',
+      example: ['日期匹配', '金额匹配', '商户相似'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: [
+    'confidence',
+    'sourceTransaction',
+    'targetTransaction',
+    'similarity',
+    'reasons'
+  ]
+} as const;
+
+export const $NlpRuleConfirmationDataDto = {
+  type: 'object',
+  properties: {
+    confidence: {
+      type: 'number',
+      description: 'Rule match confidence score (0.5-0.74)',
+      example: 0.65
+    },
+    matchedRule: {
+      type: 'object',
+      description: 'Matched rule information'
+    },
+    suggestedAccounts: {
+      type: 'object',
+      description: 'Suggested accounts from the rule'
+    },
+    alternatives: {
+      type: 'array',
+      description: 'Alternative rules that also match'
+    },
+    reasons: {
+      description: 'Human-readable reasons for the match',
+      example: [
+        'Moderate confidence (65%)',
+        'Some keywords matched (OR logic)'
+      ],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: [
+    'confidence',
+    'matchedRule',
+    'suggestedAccounts',
+    'alternatives',
+    'reasons'
+  ]
+} as const;
+
+export const $NlpAccountConfirmationDataDto = {
+  type: 'object',
+  properties: {
+    invalidAccount: {
+      type: 'string',
+      description: 'The invalid account name',
+      example: 'Expenses:Food:Coffee'
+    },
+    suggestedAccount: {
+      type: 'string',
+      description: 'Suggested replacement account',
+      example: 'Expenses:Food:Drinks'
+    },
+    similarAccounts: {
+      description: 'Similar accounts for user selection',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    errorMessage: {
+      type: 'string',
+      description: 'Error message explaining the issue',
+      example: 'No similar account found'
+    },
+    transactionContext: {
+      type: 'object',
+      description: 'Transaction context for reference'
+    }
+  },
+  required: [
+    'invalidAccount',
+    'suggestedAccount',
+    'similarAccounts',
+    'errorMessage',
+    'transactionContext'
+  ]
+} as const;
+
+export const $NlpSuggestedPayeeDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Payee ID',
+      example: 'payee-123'
+    },
+    name: {
+      type: 'string',
+      description: 'Payee name',
+      example: 'Starbucks'
+    },
+    category: {
+      type: 'string',
+      description: 'Payee category',
+      example: 'food'
+    },
+    source: {
+      type: 'string',
+      description: 'Source of the payee',
+      enum: ['user', 'global']
+    },
+    payeeProfileId: {
+      type: 'string',
+      description: 'PayeeProfile ID (if matched from global)',
+      example: 'profile-456'
+    }
+  },
+  required: ['id', 'name']
+} as const;
+
+export const $NlpAlternativePayeeDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Payee ID',
+      example: 'payee-alt-1'
+    },
+    name: {
+      type: 'string',
+      description: 'Payee name',
+      example: 'Starbucks Coffee'
+    },
+    similarity: {
+      type: 'number',
+      description: 'Similarity score (0-1)',
+      example: 0.75
+    }
+  },
+  required: ['id', 'name', 'similarity']
+} as const;
+
+export const $NlpPayeeConfirmationDataDto = {
+  type: 'object',
+  properties: {
+    confidence: {
+      type: 'number',
+      description: 'Confidence score for the payee match (0-1)',
+      example: 0.65
+    },
+    originalPayee: {
+      type: 'string',
+      description: 'Original payee string from user input',
+      example: '星巴'
+    },
+    suggestedPayee: {
+      description: 'Suggested payee to use (null when no similar payees found)',
+      nullable: true,
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSuggestedPayeeDto'
+        }
+      ]
+    },
+    similarity: {
+      type: 'number',
+      description: 'Similarity score between original and suggested (0-1)',
+      example: 0.85
+    },
+    alternatives: {
+      description: 'Alternative payee options',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/NlpAlternativePayeeDto'
+      }
+    },
+    reasons: {
+      description: 'Human-readable reasons for the match',
+      example: ['Moderate similarity (65%)', 'Fuzzy match on name'],
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    }
+  },
+  required: [
+    'confidence',
+    'originalPayee',
+    'similarity',
+    'alternatives',
+    'reasons'
+  ]
+} as const;
+
+export const $RecurringMatchInfoDto = {
+  type: 'object',
+  properties: {
+    expectedId: {
+      type: 'string',
+      description: 'Expected transaction ID'
+    },
+    ruleId: {
+      type: 'string',
+      description: 'Recurring rule ID'
+    },
+    ruleName: {
+      type: 'string',
+      description: 'Rule name for display'
+    },
+    ruleIcon: {
+      type: 'string',
+      description: 'Rule icon'
+    },
+    expectedDate: {
+      type: 'string',
+      description: 'Expected date (YYYY-MM-DD)',
+      example: '2026-01-05'
+    },
+    expectedAmount: {
+      type: 'number',
+      description: 'Expected amount',
+      example: 3000
+    },
+    confidence: {
+      type: 'number',
+      description: 'Match confidence score (0-1)',
+      example: 0.88
+    },
+    isAutoMatched: {
+      type: 'boolean',
+      description: 'Whether auto-matched (confidence >= 0.82)'
+    }
+  },
+  required: [
+    'expectedId',
+    'ruleId',
+    'ruleName',
+    'expectedDate',
+    'expectedAmount',
+    'confidence',
+    'isAutoMatched'
+  ]
+} as const;
+
+export const $NlpSuggestedAccountDto = {
+  type: 'object',
+  properties: {
+    account: {
+      type: 'string',
+      description: 'Suggested account path',
+      example: 'Assets:Bank:Checking'
+    },
+    confidence: {
+      type: 'number',
+      description: 'Confidence score for this suggestion (0-1)',
+      example: 0.9
+    }
+  },
+  required: ['account']
+} as const;
+
+export const $NlpSuggestedAccountsDto = {
+  type: 'object',
+  properties: {
+    source: {
+      description:
+        'Source account suggestion (where money comes from). For expense: asset/liability account. For income: income account.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSuggestedAccountDto'
+        }
+      ]
+    },
+    destination: {
+      description:
+        'Destination account suggestion (where money goes to). For expense: expense account. For income: asset/liability account.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSuggestedAccountDto'
+        }
+      ]
+    }
+  }
+} as const;
+
+export const $NlpDefaultAccountsDto = {
+  type: 'object',
+  properties: {
+    asset: {
+      type: 'string',
+      description: 'Default asset account',
+      example: 'Assets:Bank:Checking'
+    },
+    expense: {
+      type: 'string',
+      description: 'Default expense account',
+      example: 'Expenses:Uncategorized'
+    },
+    income: {
+      type: 'string',
+      description: 'Default income account',
+      example: 'Income:Uncategorized'
+    },
+    liability: {
+      type: 'string',
+      description: 'Default liability account',
+      example: 'Liabilities:CreditCard'
+    }
+  },
+  required: ['asset', 'expense', 'income', 'liability']
+} as const;
+
+export const $NlpResponseDto = {
+  type: 'object',
+  properties: {
+    status: {
+      type: 'string',
+      description: 'Response status',
+      enum: ['success', 'pending', 'error']
+    },
+    action: {
+      type: 'string',
+      description: 'Action taken or requested',
+      enum: [
+        'created',
+        'ask',
+        'confirm',
+        'confirm_duplicate',
+        'confirm_rule',
+        'confirm_account',
+        'confirm_payee',
+        'cancel'
+      ]
+    },
+    intent: {
+      type: 'string',
+      description:
+        'Transaction intent detected by EntityRouter (v6.0: 5 core intents). Frontend uses this to render scenario-specific form fields.',
+      enum: ['expense', 'asset', 'income', 'liability', 'equity'],
+      example: 'expense'
+    },
+    assetSubType: {
+      type: 'string',
+      description:
+        'Asset sub-type (only present when intent is "asset"). Determines which asset-related form to render.',
+      enum: ['transfer', 'banking', 'investment'],
+      example: 'investment'
+    },
+    liabilitySubType: {
+      type: 'string',
+      description:
+        'Liability sub-type (only present when intent is "liability"). borrow: borrowing money (Liabilities → Assets), repay: repaying debt (Assets → Liabilities).',
+      enum: ['borrow', 'repay'],
+      example: 'borrow'
+    },
+    equitySubType: {
+      type: 'string',
+      description:
+        'Equity sub-type (only present when intent is "equity"). opening: account opening balance (Equity → Assets), adjustment: balance correction.',
+      enum: ['opening', 'adjustment'],
+      example: 'opening'
+    },
+    paymentSource: {
+      type: 'string',
+      description:
+        'Payment source for expense transactions (v6.1). Indicates whether payment comes from asset or liability account. Only present when intent is "expense".',
+      enum: ['asset', 'liability'],
+      example: 'liability'
+    },
+    liabilityHint: {
+      type: 'string',
+      description:
+        'Liability account type hint for credit card/BNPL spending (v6.1). Only present when paymentSource is "liability". Values: CreditCard, Huabei, Baitiao',
+      example: 'CreditCard'
+    },
+    message: {
+      type: 'string',
+      description:
+        'Human-readable message (for ask or error actions). Deprecated: Use messageKey for i18n support.',
+      example: 'How much did you spend?',
+      deprecated: true
+    },
+    messageKey: {
+      type: 'string',
+      description:
+        'i18n message key for frontend translation. Use this instead of message for internationalization support.',
+      example: 'nlp.slot.prompt'
+    },
+    messageParams: {
+      type: 'object',
+      description:
+        'Parameters for message interpolation. Used with messageKey for dynamic values in translated messages.',
+      example: {
+        slot: 'amount',
+        name: 'Starbucks',
+        similarity: 85
+      }
+    },
+    sessionId: {
+      type: 'string',
+      description:
+        'Session ID for multi-turn dialogue. Must be included in subsequent requests to continue the conversation.',
+      example: 'session_abc123'
+    },
+    waitingFor: {
+      type: 'string',
+      description: 'Which slot is waiting for user input',
+      example: 'amount'
+    },
+    transaction: {
+      description: 'Created transaction info (for created action)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpTransactionInfoDto'
+        }
+      ]
+    },
+    parsedData: {
+      description:
+        'Parsed data for confirmation (when action is "confirm"). Contains extracted fields that user should verify before transaction creation.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpParsedDataDto'
+        }
+      ]
+    },
+    duplicateData: {
+      description:
+        'Duplicate detection data (when action is "confirm_duplicate"). Contains information about potential duplicate transaction for user confirmation.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpDuplicateConfirmationDataDto'
+        }
+      ]
+    },
+    ruleData: {
+      description:
+        'Rule match data (when action is "confirm_rule"). Contains information about medium-confidence rule match for user confirmation.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpRuleConfirmationDataDto'
+        }
+      ]
+    },
+    accountData: {
+      description:
+        'Account validation data (when action is "confirm_account"). Contains information about invalid account for user correction.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpAccountConfirmationDataDto'
+        }
+      ]
+    },
+    payeeData: {
+      description:
+        'Payee confirmation data (when action is "confirm_payee"). Contains information about medium/low confidence payee match for user confirmation.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpPayeeConfirmationDataDto'
+        }
+      ]
+    },
+    confidence: {
+      type: 'number',
+      description: 'Overall confidence score (0-1)',
+      example: 0.85
+    },
+    confidenceThreshold: {
+      type: 'number',
+      description:
+        'Confidence threshold for automatic creation (default: 0.75). When confidence < threshold, action will be "confirm" requiring user verification.',
+      example: 0.75
+    },
+    recurringMatch: {
+      description:
+        'Recurring transaction match info (when action is "created"). Contains match details when transaction matches a pending expected transaction.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/RecurringMatchInfoDto'
+        }
+      ]
+    },
+    recurringSuggestion: {
+      description:
+        'Recurring rule creation suggestion (when action is "created"). Contains suggestion to create a recurring rule based on detected patterns. Only present when no existing rule matched and similar historical transactions were found.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/RecurringSuggestionDto'
+        }
+      ]
+    },
+    suggestedAccounts: {
+      description:
+        'Suggested accounts for this transaction. Contains recommended source and destination accounts based on the detected intent and rules.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpSuggestedAccountsDto'
+        }
+      ]
+    },
+    defaultAccounts: {
+      description:
+        'Default accounts for the user/region. These are fallback accounts used when no specific suggestion is available.',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NlpDefaultAccountsDto'
+        }
+      ]
+    }
+  },
+  required: ['status', 'action']
+} as const;
+
+export const $BalanceByCurrencyDto = {
+  type: 'object',
+  properties: {
+    currency: {
+      type: 'string',
+      description: 'ISO 4217 currency code',
+      example: 'CNY'
+    },
+    balance: {
+      type: 'string',
+      description: 'Balance amount',
+      example: '50000.00'
+    }
+  },
+  required: ['currency', 'balance']
+} as const;
+
+export const $NetWorthByCurrencyDto = {
+  type: 'object',
+  properties: {
+    netWorth: {
+      description: 'Net worth by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    assets: {
+      description: 'Assets by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    liabilities: {
+      description: 'Liabilities by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    }
+  },
+  required: ['netWorth', 'assets', 'liabilities']
+} as const;
+
+export const $ConvertedNetWorthDto = {
+  type: 'object',
+  properties: {
+    baseCurrency: {
+      type: 'string',
+      description: 'Base currency for conversion',
+      example: 'CNY'
+    },
+    netWorth: {
+      type: 'string',
+      description: 'Converted net worth',
+      example: '500000.00'
+    },
+    assets: {
+      type: 'string',
+      description: 'Converted assets',
+      example: '600000.00'
+    },
+    liabilities: {
+      type: 'string',
+      description: 'Converted liabilities',
+      example: '100000.00'
+    },
+    exchangeRates: {
+      type: 'object',
+      description: 'Exchange rates used for conversion',
+      example: {
+        USD: '7.200000',
+        EUR: '7.800000'
+      }
+    }
+  },
+  required: [
+    'baseCurrency',
+    'netWorth',
+    'assets',
+    'liabilities',
+    'exchangeRates'
+  ]
+} as const;
+
+export const $ExchangeRateWarningDto = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      description: 'Warning type',
+      example: 'MISSING_EXCHANGE_RATE'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency without exchange rate',
+      example: 'EUR'
+    },
+    totalAmount: {
+      type: 'string',
+      description: 'Total amount affected',
+      example: '1000.00'
+    }
+  },
+  required: ['type', 'currency', 'totalAmount']
+} as const;
+
+export const $NetWorthResponseDto = {
+  type: 'object',
+  properties: {
+    netWorth: {
+      type: 'string',
+      description:
+        'Total net worth (assets - liabilities, converted to base currency)',
+      example: '500000.00'
+    },
+    assets: {
+      type: 'string',
+      description: 'Total assets value (converted)',
+      example: '600000.00'
+    },
+    liabilities: {
+      type: 'string',
+      description: 'Total liabilities value (positive number, converted)',
+      example: '100000.00'
+    },
+    monthlyReturn: {
+      type: 'string',
+      description: 'Monthly return (change from last month)',
+      example: '15000.00'
+    },
+    monthlyReturnPercentage: {
+      type: 'string',
+      description: 'Monthly return percentage',
+      example: '3.15'
+    },
+    currency: {
+      type: 'string',
+      description: 'Base currency code',
+      example: 'CNY'
+    },
+    asOf: {
+      type: 'string',
+      description: 'Data as of date (ISO 8601)',
+      example: '2024-06-15T00:00:00.000Z'
+    },
+    byCurrency: {
+      description: 'Balances grouped by original currency',
+      allOf: [
+        {
+          $ref: '#/components/schemas/NetWorthByCurrencyDto'
+        }
+      ]
+    },
+    converted: {
+      description:
+        'Converted values in base currency (undefined if no exchange rates available)',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ConvertedNetWorthDto'
+        }
+      ]
+    },
+    warnings: {
+      description: 'Exchange rate warnings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
+    }
+  },
+  required: [
+    'netWorth',
+    'assets',
+    'liabilities',
+    'monthlyReturn',
+    'monthlyReturnPercentage',
+    'currency',
+    'asOf'
+  ]
+} as const;
+
+export const $AccountItemDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Account ID'
+    },
+    name: {
+      type: 'string',
+      description: 'Full account name',
+      example: 'Assets:Bank:CMB:Savings'
+    },
+    displayName: {
+      type: 'string',
+      description: 'Display name (last part of account path)',
+      example: 'Savings'
+    },
+    balance: {
+      type: 'string',
+      description: 'Account balance',
+      example: '50000.00'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'CNY'
+    }
+  },
+  required: ['id', 'name', 'displayName', 'balance', 'currency']
+} as const;
+
+export const $PlatformGroupDto = {
+  type: 'object',
+  properties: {
+    platformId: {
+      type: 'string',
+      description: 'Platform ID'
+    },
+    platformName: {
+      type: 'string',
+      description: 'Platform display name',
+      example: 'CMB Bank'
+    },
+    accounts: {
+      description: 'Accounts within this platform',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountItemDto'
+      }
+    },
+    totalBalance: {
+      type: 'string',
+      description: 'Total balance across all accounts in platform',
+      example: '100000.00'
+    }
+  },
+  required: ['platformId', 'platformName', 'accounts', 'totalBalance']
+} as const;
+
+export const $AccountsSummaryDto = {
+  type: 'object',
+  properties: {
+    totalAccounts: {
+      type: 'number',
+      description: 'Total number of accounts'
+    },
+    totalPlatforms: {
+      type: 'number',
+      description: 'Total number of platforms'
+    }
+  },
+  required: ['totalAccounts', 'totalPlatforms']
+} as const;
+
+export const $AccountsResponseDto = {
+  type: 'object',
+  properties: {
+    groups: {
+      description: 'Account groups by platform',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/PlatformGroupDto'
+      }
+    },
+    summary: {
+      description: 'Summary statistics',
+      allOf: [
+        {
+          $ref: '#/components/schemas/AccountsSummaryDto'
+        }
+      ]
+    }
+  },
+  required: ['groups', 'summary']
+} as const;
+
+export const $AccountItemWithAssetClassDto = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      description: 'Account ID'
+    },
+    name: {
+      type: 'string',
+      description: 'Full account name',
+      example: 'Assets:Bank:CMB:Savings'
+    },
+    displayName: {
+      type: 'string',
+      description: 'Display name (last part of account path)',
+      example: 'Savings'
+    },
+    balance: {
+      type: 'string',
+      description: 'Account balance',
+      example: '50000.00'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency code',
+      example: 'CNY'
+    },
+    assetClass: {
+      type: 'string',
+      description: 'Asset class',
+      example: 'LIQUIDITY'
+    },
+    assetSubClass: {
+      type: 'string',
+      description: 'Asset sub-class (Prisma-compatible)',
+      example: 'RETIREMENT_ACCOUNT'
+    },
+    regionalSubClass: {
+      type: 'string',
+      description: 'Regional sub-class (region-specific, for display)',
+      example: 'FOUR_ZERO_ONE_K'
+    },
+    riskLevel: {
+      type: 'string',
+      description: 'Risk level',
+      example: 'LOW'
+    }
+  },
+  required: ['id', 'name', 'displayName', 'balance', 'currency', 'assetClass']
+} as const;
+
+export const $AssetClassGroupDto = {
+  type: 'object',
+  properties: {
+    assetClass: {
+      type: 'string',
+      description: 'Asset class name',
+      example: 'LIQUIDITY',
+      enum: [
+        'LIQUIDITY',
+        'EQUITY',
+        'FIXED_INCOME',
+        'PRECIOUS_METALS',
+        'COMMODITY',
+        'INSURANCE',
+        'ALTERNATIVE_INVESTMENT',
+        'PERSONAL_ASSETS',
+        'LIABILITY',
+        'REAL_ESTATE',
+        'INDEX'
+      ]
+    },
+    assetSubClass: {
+      type: 'string',
+      description: 'Asset sub-class name',
+      example: 'DEPOSIT'
+    },
+    accounts: {
+      description: 'Accounts within this asset class',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountItemWithAssetClassDto'
+      }
+    },
+    balanceByCurrency: {
+      description: 'Balances grouped by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    convertedBalance: {
+      type: 'string',
+      description: 'Converted balance in base currency',
+      example: '100000.00'
+    }
+  },
+  required: ['assetClass', 'accounts', 'balanceByCurrency']
+} as const;
+
+export const $AccountExchangeRateWarningDto = {
+  type: 'object',
+  properties: {
+    type: {
+      type: 'string',
+      description: 'Warning type',
+      example: 'MISSING_EXCHANGE_RATE'
+    },
+    currency: {
+      type: 'string',
+      description: 'Currency without exchange rate',
+      example: 'USD'
+    },
+    accounts: {
+      description: 'Affected account paths',
+      type: 'array',
+      items: {
+        type: 'string'
+      }
+    },
+    totalAmount: {
+      type: 'string',
+      description: 'Total amount in this currency',
+      example: '5000.00'
+    }
+  },
+  required: ['type', 'currency', 'accounts', 'totalAmount']
+} as const;
+
+export const $AssetClassSummaryDto = {
+  type: 'object',
+  properties: {
+    totalAccounts: {
+      type: 'number',
+      description: 'Total number of accounts'
+    },
+    totalAssetClasses: {
+      type: 'number',
+      description: 'Total number of asset classes'
+    },
+    baseCurrency: {
+      type: 'string',
+      description: 'Base currency for conversion',
+      example: 'CNY'
+    },
+    warnings: {
+      description: 'Exchange rate warnings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AccountExchangeRateWarningDto'
+      }
+    }
+  },
+  required: ['totalAccounts', 'totalAssetClasses', 'baseCurrency']
+} as const;
+
+export const $AssetClassAccountsResponseDto = {
+  type: 'object',
+  properties: {
+    groups: {
+      description: 'Account groups by asset class',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/AssetClassGroupDto'
+      }
+    },
+    summary: {
+      description: 'Summary statistics',
+      allOf: [
+        {
+          $ref: '#/components/schemas/AssetClassSummaryDto'
+        }
+      ]
+    }
+  },
+  required: ['groups', 'summary']
+} as const;
+
+export const $CashFlowByCurrencyDto = {
+  type: 'object',
+  properties: {
+    income: {
+      description: 'Income by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    expense: {
+      description: 'Expense by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    },
+    netSavings: {
+      description: 'Net savings by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/BalanceByCurrencyDto'
+      }
+    }
+  },
+  required: ['income', 'expense', 'netSavings']
+} as const;
+
+export const $ConvertedCashFlowDto = {
+  type: 'object',
+  properties: {
+    baseCurrency: {
+      type: 'string',
+      description: 'Base currency for conversion',
+      example: 'CNY'
+    },
+    income: {
+      type: 'string',
+      description: 'Converted income',
+      example: '25000.00'
+    },
+    expense: {
+      type: 'string',
+      description: 'Converted expense',
+      example: '18000.00'
+    },
+    netSavings: {
+      type: 'string',
+      description: 'Converted net savings',
+      example: '7000.00'
+    },
+    exchangeRates: {
+      type: 'object',
+      description: 'Exchange rates used for conversion',
+      example: {
+        USD: '7.200000'
+      }
+    }
+  },
+  required: ['baseCurrency', 'income', 'expense', 'netSavings', 'exchangeRates']
+} as const;
+
+export const $CashFlowResponseDto = {
+  type: 'object',
+  properties: {
+    period: {
+      type: 'string',
+      description: 'Period identifier (YYYY-MM)',
+      example: '2024-06'
+    },
+    income: {
+      type: 'string',
+      description: 'Total income for the period (converted)',
+      example: '25000.00'
+    },
+    expense: {
+      type: 'string',
+      description: 'Total expenses for the period (converted)',
+      example: '18000.00'
+    },
+    netSavings: {
+      type: 'string',
+      description: 'Net savings (income - expense, converted)',
+      example: '7000.00'
+    },
+    savingsRate: {
+      type: 'string',
+      description: 'Savings rate percentage (netSavings / income * 100)',
+      example: '28.00'
+    },
+    currency: {
+      type: 'string',
+      description: 'Base currency code',
+      example: 'CNY'
+    },
+    byCurrency: {
+      description: 'Cash flow grouped by original currency',
+      allOf: [
+        {
+          $ref: '#/components/schemas/CashFlowByCurrencyDto'
+        }
+      ]
+    },
+    converted: {
+      description: 'Converted values in base currency',
+      allOf: [
+        {
+          $ref: '#/components/schemas/ConvertedCashFlowDto'
+        }
+      ]
+    },
+    warnings: {
+      description: 'Exchange rate warnings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
+    }
+  },
+  required: [
+    'period',
+    'income',
+    'expense',
+    'netSavings',
+    'savingsRate',
+    'currency'
+  ]
+} as const;
+
+export const $CurrencyBalanceDto = {
+  type: 'object',
+  properties: {
+    currency: {
+      type: 'string',
+      description: 'ISO 4217 currency code',
+      example: 'CNY'
+    },
+    balance: {
+      type: 'string',
+      description: 'Balance amount',
+      example: '500000.00'
+    }
+  },
+  required: ['currency', 'balance']
+} as const;
+
+export const $TimeSeriesPointDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Date in YYYY-MM-DD format',
+      example: '2024-06-15'
+    },
+    value: {
+      type: 'string',
+      description: 'Value at this date (in base currency)',
+      example: '500000.00'
+    },
+    change: {
+      type: 'object',
+      description: 'Change from previous point',
+      example: '5000.00'
+    },
+    byCurrency: {
+      description: 'Multi-currency breakdown for this point',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CurrencyBalanceDto'
+      }
+    }
+  },
+  required: ['date', 'value']
+} as const;
+
+export const $TrendSummaryDto = {
+  type: 'object',
+  properties: {
+    startValue: {
+      type: 'string',
+      description: 'Value at start of period',
+      example: '450000.00'
+    },
+    endValue: {
+      type: 'string',
+      description: 'Value at end of period',
+      example: '500000.00'
+    },
+    totalChange: {
+      type: 'string',
+      description: 'Total change over period',
+      example: '50000.00'
+    },
+    totalChangePercentage: {
+      type: 'string',
+      description: 'Total change percentage',
+      example: '+11.11%'
+    }
+  },
+  required: ['startValue', 'endValue', 'totalChange', 'totalChangePercentage']
+} as const;
+
+export const $MultiCurrencyPointDto = {
+  type: 'object',
+  properties: {
+    date: {
+      type: 'string',
+      description: 'Date in YYYY-MM-DD format',
+      example: '2024-06-15'
+    },
+    byCurrency: {
+      description: 'Balances by currency',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/CurrencyBalanceDto'
+      }
+    }
+  },
+  required: ['date', 'byCurrency']
+} as const;
+
+export const $PortfolioTrendsResponseDto = {
+  type: 'object',
+  properties: {
+    series: {
+      description: 'Time series data points',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/TimeSeriesPointDto'
+      }
+    },
+    summary: {
+      description: 'Period summary',
+      allOf: [
+        {
+          $ref: '#/components/schemas/TrendSummaryDto'
+        }
+      ]
+    },
+    period: {
+      type: 'string',
+      description: 'Period requested',
+      example: '6m'
+    },
+    granularity: {
+      type: 'string',
+      description: 'Data granularity',
+      example: 'month'
+    },
+    currency: {
+      type: 'string',
+      description: 'Base currency for converted values',
+      example: 'CNY'
+    },
+    byCurrency: {
+      description:
+        'Multi-currency time series (each point has currency breakdown)',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/MultiCurrencyPointDto'
+      }
+    },
+    warnings: {
+      description: 'Exchange rate warnings',
+      type: 'array',
+      items: {
+        $ref: '#/components/schemas/ExchangeRateWarningDto'
+      }
+    }
+  },
+  required: ['series', 'summary', 'period', 'granularity', 'currency']
+} as const;
+
+export const $GenerateSnapshotBody = {
+  type: 'object',
+  properties: {}
+} as const;
+
+export const $GenerateSnapshotResponse = {
+  type: 'object',
+  properties: {}
+} as const;
+
+export const $BackfillSnapshotsBody = {
+  type: 'object',
+  properties: {}
+} as const;
+
+export const $BackfillSnapshotsResponse = {
+  type: 'object',
+  properties: {}
+} as const;
+
+export const $AnonymousLoginDto = {
+  type: 'object',
+  properties: {
+    accessToken: {
+      type: 'string',
+      description: 'Access token for anonymous login'
+    }
+  },
+  required: ['accessToken']
+} as const;