Add OpenAPI specification for system-log service.

apps/system-log/openapi.yaml

@@ -0,0 +1,427 @@
+openapi: 3.0.3
+
+info:
+  title: system-log API
+  version: "1.0.0"
+  description: |
+    REST API сервиса **system-log** (`platform/system-log`) — приём и выборка
+    записей журнала системных событий (кто, над чем и какое действие совершил).
+
+    Сервис написан на Go (фреймворк **Fiber v2**). Роутинг собирается в
+    `internal/controller/http/v0`: базовая группа `/api` → подгруппа `v0` →
+    ресурс `/system_log`. Плюс служебный эндпоинт `/ping`.
+
+    ### Аутентификация
+    Аутентификация на уровне приложения не настроена — эндпоинты доступны без
+    авторизации. Ограничение доступа обеспечивается сетевым слоем (ClusterIP /
+    Istio), а не самим сервисом.
+
+    ### Пагинация
+    Списочные ответы возвращают объект `{ count, limit, offset, next, prev, result }`.
+    Управление — параметрами `limit` и `offset`. Значения по умолчанию:
+    `limit = 100`, `offset = 0` (константы `_defaultLimit` / `_defaultOffset`
+    в `internal/controller/http/v0/systemlog/controller.go`). Ссылки `next`/`prev`
+    формируются в `pkg/pagination`. У эндпоинта поиска (`POST /search`) полей
+    `next`/`prev` нет.
+
+    ### Фильтрация
+    Массивные фильтры (`actor_ids`, `event_names`, `model_names`, `instance_ids`,
+    `target_ids`, `company_ids`, `statuses`, `message`) в GET-запросе передаются
+    списком значений через запятую и парсятся Fiber `QueryParser`. Поля
+    `instance_uuids` и `resource_uuids` разбираются вручную (`strings.Split` +
+    `uuid.Parse`) — при невалидном UUID возвращается `400`.
+
+    ### Замечания (расхождения кода)
+    - `metadata` в фильтре объявлено как `map[string]interface{}` с query-тегом,
+      но при передаче в query-строке Fiber не восстановит вложенный объект —
+      фильтрация по `metadata` практически применима через тело `POST /search`.
+    - Поле `is_processed_by_worker` присутствует в фильтре, но отдаётся в выборку
+      наравне с остальными; используется воркером обогащения.
+    - Ответ `POST /system_log/` при успехе — простая строка `"OK"` (не объект).
+
+servers:
+  - url: https://api.sarex.io
+    description: Production (ingress)
+  - url: https://stage-api.sarex.io
+    description: Stage (ingress)
+  - url: http://backend-svc.system-log.svc.cluster.local
+    description: Внутрикластерный адрес (ClusterIP, порт 80 → 8000)
+  - url: http://localhost:8888
+    description: Локальный запуск (config.env)
+
+tags:
+  - name: system_log
+    description: Записи журнала системных событий
+  - name: service
+    description: Служебные эндпоинты
+
+paths:
+  # ==========================================================================
+  # Service
+  # ==========================================================================
+  /ping:
+    get:
+      tags: [service]
+      summary: Проверка живости
+      description: Liveness/readiness-проба (используется в probes деплоймента). Всегда `200 OK` без тела.
+      operationId: ping
+      security: []
+      responses:
+        '200':
+          description: OK
+
+  # ==========================================================================
+  # System log
+  # ==========================================================================
+  /api/v0/system_log/:
+    get:
+      tags: [system_log]
+      summary: Список записей журнала (с фильтрами)
+      description: |
+        Возвращает отфильтрованные записи журнала с пагинацией.
+        Массивные параметры принимают список значений через запятую.
+      operationId: getSystemLogRecords
+      parameters:
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Offset'
+        - name: actor_ids
+          in: query
+          description: ID авторов событий; список значений через запятую
+          example: "1,2,3"
+          schema: { type: string }
+        - name: event_names
+          in: query
+          description: Названия событий (напр. create, edit, delete, transfer); через запятую
+          example: "create,edit,delete"
+          schema: { type: string }
+        - name: model_names
+          in: query
+          description: Названия моделей (напр. document, bundle, project); через запятую
+          example: "document,bundle"
+          schema: { type: string }
+        - name: instance_ids
+          in: query
+          description: ID сущностей; список значений через запятую
+          example: "1,2,3"
+          schema: { type: string }
+        - name: instance_uuids
+          in: query
+          description: UUID сущностей; список значений через запятую (валидируются как UUID)
+          example: "3fa85f64-5717-4562-b3fc-2c963f66afa6"
+          schema: { type: string }
+        - name: resource_uuids
+          in: query
+          description: UUID ресурсов; список значений через запятую (валидируются как UUID)
+          schema: { type: string }
+        - name: registered_at_gte
+          in: query
+          description: Нижняя граница времени регистрации (>=)
+          example: "2025-02-16T15:04:05Z"
+          schema: { type: string, format: date-time }
+        - name: registered_at_lte
+          in: query
+          description: Верхняя граница времени регистрации (<=)
+          example: "2025-02-16T15:04:05Z"
+          schema: { type: string, format: date-time }
+        - name: instance_path
+          in: query
+          description: Путь сущности (ltree), точное совпадение
+          example: "1.79899.80131"
+          schema: { type: string }
+        - name: target_ids
+          in: query
+          description: ID целей; список значений через запятую
+          example: "1,2,3"
+          schema: { type: string }
+        - name: target_path
+          in: query
+          description: Путь цели (ltree), точное совпадение
+          example: "4.3.2.1"
+          schema: { type: string }
+        - name: company_ids
+          in: query
+          description: ID компаний; список значений через запятую
+          example: "1,2,3"
+          schema: { type: string }
+        - name: statuses
+          in: query
+          description: Подстатусы события; список значений через запятую
+          example: "add_bundle,delete_bundle,rename_document"
+          schema: { type: string }
+        - name: message
+          in: query
+          description: Сообщения; список значений через запятую
+          schema: { type: string }
+        - name: is_processed_by_worker
+          in: query
+          description: Признак обработки записи воркером обогащения
+          schema: { type: boolean }
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SystemLogListResponse' }
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+    post:
+      tags: [system_log]
+      summary: Создать записи журнала
+      description: |
+        Принимает пакет записей в поле `system_logs`. Для каждой записи должно
+        быть задано **ровно одно** из `instance_id` / `instance_uuid`
+        (не оба и не ни одного — иначе `400`). Обязательны `event_name` и
+        `model_name`. При успехе возвращается строка `"OK"`.
+      operationId: createSystemLogRecords
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/SystemLogCreateRequest' }
+      responses:
+        '200':
+          description: Записи созданы
+          content:
+            application/json:
+              schema:
+                type: string
+                example: "OK"
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/v0/system_log/search:
+    post:
+      tags: [system_log]
+      summary: Поиск записей журнала (фильтры в теле)
+      description: |
+        Аналог GET-выборки, но фильтры передаются в теле запроса
+        (`filters`). Позволяет использовать сложные фильтры (в т.ч. `metadata`),
+        которые неудобно кодировать в query-строке. В ответе нет `next`/`prev`.
+      operationId: searchSystemLogs
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/SystemLogSearchRequest' }
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SystemLogSearchResponse' }
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+# ============================================================================
+components:
+  parameters:
+    Limit:
+      name: limit
+      in: query
+      description: Кол-во записей на странице
+      schema: { type: integer, format: uint64, default: 100 }
+    Offset:
+      name: offset
+      in: query
+      description: Смещение от начала выборки
+      schema: { type: integer, format: uint64, default: 0, minimum: 0 }
+
+  responses:
+    BadRequest:
+      description: Ошибка разбора/валидации запроса
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ControllerError' }
+    InternalError:
+      description: Внутренняя ошибка сервиса
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/ControllerError' }
+
+  schemas:
+    # ---- Общие ----
+    ControllerError:
+      type: object
+      description: Формат ошибки (`internal/controller/errors.go`, `ErrorToResponse`).
+      properties:
+        message: { type: string, example: "error parse body" }
+        status_code: { type: integer, example: 400 }
+
+    # ---- Доменная запись ----
+    SystemLog:
+      type: object
+      description: Запись журнала системных событий (`internal/entity/system_log.go`).
+      properties:
+        actor_id:
+          type: integer
+          format: uint64
+          description: ID автора события
+          example: 1023
+        event_name:
+          type: string
+          description: Название события (напр. edit, create, copy)
+          example: "edit"
+        model_name:
+          type: string
+          description: Над какой сущностью произошло событие (напр. document, inspection)
+          example: "document"
+        instance_id:
+          type: integer
+          format: uint64
+          nullable: true
+          description: ID сущности (для моделей с числовым ключом)
+          example: 80131
+        instance_uuid:
+          type: string
+          format: uuid
+          nullable: true
+          description: UUID сущности (для моделей с UUID-ключом)
+        registered_at:
+          type: string
+          format: date-time
+          nullable: true
+          description: Время регистрации события
+          example: "2023-05-04T08:09:53.852916Z"
+        instance_path:
+          type: string
+          nullable: true
+          description: Путь сущности (ltree)
+          example: "1.79899.80131"
+        target_id:
+          type: integer
+          format: uint64
+          nullable: true
+          description: ID цели события
+        company_id:
+          type: integer
+          format: uint64
+          nullable: true
+          description: ID компании (может обогащаться воркером)
+          example: 1
+        metadata:
+          type: object
+          additionalProperties: true
+          description: Произвольные дополнительные данные о событии
+          example: { "document_name": "КСГ.pdf", "count_bundle": 3 }
+        message:
+          type: string
+          nullable: true
+          description: Произвольное сообщение
+          example: "bundle was deleted from document"
+        status:
+          type: string
+          nullable: true
+          description: Подстатус события
+          example: "delete_bundle"
+        resource_uuid:
+          type: string
+          format: uuid
+          nullable: true
+          description: UUID связанного ресурса
+        target_path:
+          type: string
+          nullable: true
+          description: Путь цели (ltree)
+      required: [event_name, model_name]
+
+    # ---- Запросы ----
+    SystemLogCreateRequest:
+      type: object
+      description: >
+        Пакет записей для создания. Для каждой записи обязательно ровно одно из
+        instance_id / instance_uuid.
+      properties:
+        system_logs:
+          type: array
+          minItems: 1
+          items: { $ref: '#/components/schemas/SystemLog' }
+      required: [system_logs]
+
+    SystemLogFilter:
+      type: object
+      description: Набор фильтров выборки (`entity.SystemLogFilter`).
+      properties:
+        limit: { type: integer, format: uint64, default: 100 }
+        offset: { type: integer, format: uint64, default: 0 }
+        actor_ids:
+          type: array
+          items: { type: integer, format: uint64 }
+        event_names:
+          type: array
+          items: { type: string }
+        model_names:
+          type: array
+          items: { type: string }
+        instance_ids:
+          type: array
+          items: { type: integer, format: uint64 }
+        instance_uuids:
+          type: array
+          items: { type: string, format: uuid }
+        registered_at_gte: { type: string, format: date-time, nullable: true }
+        registered_at_lte: { type: string, format: date-time, nullable: true }
+        instance_path: { type: string, nullable: true }
+        target_ids:
+          type: array
+          items: { type: integer, format: uint64 }
+        target_path: { type: string, nullable: true }
+        company_ids:
+          type: array
+          items: { type: integer, format: uint64 }
+        statuses:
+          type: array
+          items: { type: string }
+        message: { type: string, nullable: true }
+        metadata:
+          type: object
+          additionalProperties: true
+        resource_uuids:
+          type: array
+          items: { type: string, format: uuid }
+        is_processed_by_worker: { type: boolean, nullable: true }
+
+    SystemLogSearchRequest:
+      type: object
+      description: Тело запроса поиска (`SearchParams` в `dto.go`).
+      properties:
+        limit: { type: integer, format: uint64, default: 100 }
+        offset: { type: integer, format: uint64, default: 0 }
+        filters: { $ref: '#/components/schemas/SystemLogFilter' }
+
+    # ---- Ответы ----
+    SystemLogListResponse:
+      type: object
+      description: Ответ списочной выборки (`entity.SystemLogRecordsRequest`).
+      properties:
+        count: { type: integer, format: uint64, example: 1226 }
+        limit: { type: integer, format: uint64, nullable: true, example: 100 }
+        offset: { type: integer, format: uint64, nullable: true, example: 0 }
+        next:
+          type: string
+          nullable: true
+          example: "http://localhost:8888/api/v0/system_log?limit=100&offset=100"
+        prev:
+          type: string
+          nullable: true
+        result:
+          type: array
+          items: { $ref: '#/components/schemas/SystemLog' }
+      required: [count, result]
+
+    SystemLogSearchResponse:
+      type: object
+      description: Ответ поиска (`entity.SystemLogRecordsSearch`) — без next/prev.
+      properties:
+        count: { type: integer, format: uint64, example: 1226 }
+        limit: { type: integer, format: uint64, nullable: true, example: 100 }
+        offset: { type: integer, format: uint64, nullable: true, example: 0 }
+        result:
+          type: array
+          items: { $ref: '#/components/schemas/SystemLog' }
+      required: [count, result]