spec: add stock screener

2026-10-11 10:44:30 +03:00
parent 13e3e53d06
commit ed6cf299f2
10 changed files with 653 additions and 0 deletions
@@ -0,0 +1,177 @@
+openapi: 3.0.3
+info:
+  title: WealthLedger stock screener target contract
+  version: 1.0.0
+  description: Целевой контракт change; исполняемый HTTP-контракт после реализации генерирует backend.
+paths:
+  /api/v1/stocks/screener/search:
+    post:
+      operationId: createStockScreenerSearch
+      summary: Получить новый результат скринера по полному каталогу акций
+      security:
+        - bearer: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/StockScreenerCriteria'
+      responses:
+        '200':
+          description: Первая страница нового результата, включая подтверждённый пустой список
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StockScreenerPage'
+        '400':
+          $ref: '#/components/responses/Problem'
+        '401':
+          $ref: '#/components/responses/Problem'
+        '503':
+          $ref: '#/components/responses/Problem'
+  /api/v1/stocks/screener/search/{searchId}:
+    get:
+      operationId: readStockScreenerPage
+      summary: Прочитать страницу того же зафиксированного результата
+      security:
+        - bearer: []
+      parameters:
+        - name: searchId
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Непрозрачный идентификатор результата; не является полномочием доступа.
+        - name: page
+          in: query
+          required: true
+          schema:
+            type: integer
+            minimum: 1
+          description: Номер страницы с единицы. Условия поиска при чтении страницы не меняются.
+      responses:
+        '200':
+          description: Страница зафиксированного результата с тем же временем получения каталога
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StockScreenerPage'
+        '400':
+          $ref: '#/components/responses/Problem'
+        '401':
+          $ref: '#/components/responses/Problem'
+        '404':
+          $ref: '#/components/responses/Problem'
+        '503':
+          $ref: '#/components/responses/Problem'
+components:
+  securitySchemes:
+    bearer:
+      type: http
+      scheme: bearer
+  responses:
+    Problem:
+      description: Ошибка в текущем публичном профиле WealthLedger; отсутствие результата не кодируется пустым списком.
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+  schemas:
+    Problem:
+      type: object
+      required: [status, code]
+      properties:
+        status:
+          type: integer
+        code:
+          type: string
+        title:
+          type: string
+        detail:
+          type: string
+    StockScreenerCriteria:
+      type: object
+      description: Все условия необязательны; отсутствие полей означает поиск по всем доступным к покупке акциям каталога.
+      additionalProperties: false
+      properties:
+        query:
+          type: string
+          maxLength: 80
+          description: Необязательная подстрока названия или тикера; пустая строка равнозначна отсутствию условия.
+        sector:
+          type: string
+          minLength: 1
+        shareType:
+          type: string
+          minLength: 1
+        currency:
+          type: string
+          minLength: 1
+        realExchange:
+          type: string
+          minLength: 1
+          description: Реальная площадка исполнения, не код торгового режима.
+        countryOfRisk:
+          type: string
+          minLength: 1
+          description: Код страны основного бизнеса.
+        maxLot:
+          type: integer
+          minimum: 1
+          description: Включительная верхняя граница числа бумаг в лоте.
+    StockScreenerPage:
+      type: object
+      required: [searchId, asOf, page, hasNext, items]
+      properties:
+        searchId:
+          type: string
+          description: Идентификатор только этого поиска, ограничен пользователем и подключением.
+        asOf:
+          type: string
+          format: date-time
+          description: Время получения полного списка акций от T-Invest, одинаковое на всех страницах результата.
+        page:
+          type: integer
+          minimum: 1
+        hasNext:
+          type: boolean
+        items:
+          type: array
+          maxItems: 30
+          items:
+            $ref: '#/components/schemas/StockScreenerItem'
+    StockScreenerItem:
+      type: object
+      required: [instrumentUid, name, ticker, isin, shareType, sector, currency, realExchange, countryOfRisk, lot]
+      properties:
+        instrumentUid:
+          type: string
+          format: uuid
+          description: Точный выбранный инструмент для ссылки на страницу акции; нельзя подменять неоднозначным тикером.
+        name:
+          type: string
+        ticker:
+          type: string
+          nullable: true
+        isin:
+          type: string
+          nullable: true
+        shareType:
+          type: string
+          nullable: true
+        sector:
+          type: string
+          nullable: true
+        currency:
+          type: string
+          nullable: true
+        realExchange:
+          type: string
+          nullable: true
+        countryOfRisk:
+          type: string
+          nullable: true
+        lot:
+          type: integer
+          minimum: 1
+          nullable: true