openapi: 3.1.0
info:
  title: АРМ КА — таблица гудвилла
  version: 0.1.0-draft
  description: >
    Черновик контракта AURORA-1543 (бэкенд) / AURORA-1544 (фронт). Текстовое описание, источники и открытые вопросы —
    dev/api-contract-goodwill.md; оба файла держатся одинаковыми. Деньги — строки с двумя знаками в рублях, доля
    владения — строка с четырьмя знаками. Чтение — CONSOLIDATION_VIEW, правки — CONSOLIDATION_EDIT.
servers:
  - url: /api/v1
security:
  - bearerAuth: []

paths:
  /consolidations/versions/{version_id}/goodwill:
    get:
      operationId: getGoodwillTable
      summary: Таблица гудвилла версии
      x-permission: CONSOLIDATION_VIEW
      parameters:
        - $ref: '#/components/parameters/VersionId'
      responses:
        '200':
          description: Строки пар (ГО, ДО) периметра, итоги
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GoodwillTableOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/DomainError' }

  /consolidations/versions/{version_id}/goodwill-settings:
    put:
      operationId: saveGoodwillSettings
      summary: Переключатель расчёта гудвилла версии (consolidation_version.goodwill_enabled)
      description: >
        Аудит GOODWILL_ENABLED_CHANGE; результат КФО устаревает при любом изменении значения. Выключение не стирает
        сохранённые строки (ownership_share, comment, include_in_kfo).
      x-permission: CONSOLIDATION_EDIT
      parameters:
        - $ref: '#/components/parameters/VersionId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/GoodwillSettingsIn' }
      responses:
        '200':
          description: Таблица с обновлённым флагом
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GoodwillTableOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/DomainError' }
        '409': { $ref: '#/components/responses/DomainError' }

  /consolidations/versions/{version_id}/goodwill/{head_legal_entity_id}/{subsidiary_legal_entity_id}:
    put:
      operationId: saveGoodwillRow
      summary: Сохранить строку гудвилла (создать или заменить целиком)
      description: >
        Аудит GOODWILL_ROW_EDIT; результат КФО устаревает. Вычисляемые поля (financial_investment_amount,
        charter_capital_amount, additional_capital_amount, participation_amount, goodwill_amount) в тело запроса не
        входят — пересчитываются сервером. 404 — версия или пара (head/subsidiary) не из периметра; 409 — правок
        версии; 422 — COMMENT_REQUIRED (include_in_kfo = true без комментария), INVALID_SHARE (вне 0…100 или больше
        4 знаков после запятой).
      x-permission: CONSOLIDATION_EDIT
      parameters:
        - $ref: '#/components/parameters/VersionId'
        - $ref: '#/components/parameters/HeadLegalEntityId'
        - $ref: '#/components/parameters/SubsidiaryLegalEntityId'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/GoodwillRowIn' }
      responses:
        '200':
          description: Пересчитанная строка
          content:
            application/json:
              schema: { $ref: '#/components/schemas/GoodwillRowOut' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/DomainError' }
        '409': { $ref: '#/components/responses/DomainError' }
        '422': { $ref: '#/components/responses/DomainOrValidationError' }

  /consolidations/versions/{version_id}/goodwill/export:
    get:
      operationId: exportGoodwillTable
      summary: Выгрузка таблицы гудвилла в xlsx
      description: Аудит EXPORT.
      x-permission: CONSOLIDATION_VIEW
      parameters:
        - $ref: '#/components/parameters/VersionId'
      responses:
        '200':
          description: Файл xlsx
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema: { type: string, format: binary }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/DomainError' }

components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }

  parameters:
    VersionId:
      name: version_id
      in: path
      required: true
      schema: { type: string, format: uuid }
    HeadLegalEntityId:
      name: head_legal_entity_id
      in: path
      required: true
      description: Член периметра с is_head_entity = true
      schema: { type: string, format: uuid }
    SubsidiaryLegalEntityId:
      name: subsidiary_legal_entity_id
      in: path
      required: true
      description: Любой другой член периметра
      schema: { type: string, format: uuid }

  responses:
    Unauthorized:
      description: Нет или плохой токен
    Forbidden:
      description: Нет права
      content:
        application/json:
          schema:
            type: object
            properties: { detail: { type: string } }
    DomainError:
      description: Доменная ошибка
      content:
        application/json:
          schema: { $ref: '#/components/schemas/DomainErrorOut' }
    DomainOrValidationError:
      description: Доменная ошибка или массив ошибок валидации pydantic
      content:
        application/json:
          schema:
            oneOf:
              - $ref: '#/components/schemas/DomainErrorOut'
              - type: object
                properties:
                  detail:
                    type: array
                    items:
                      type: object
                      properties:
                        loc: { type: array, items: {} }
                        msg: { type: string }
                        type: { type: string }

  schemas:
    Money:
      type: string
      pattern: '^-?\d+\.\d{2}$'
      description: Сумма в рублях, два знака; может быть отрицательной (goodwill_amount)
      examples: ['500000.00']
    Share:
      type: [string, 'null']
      pattern: '^\d{1,3}\.\d{4}$'
      description: Доля владения, % (numeric(7,4)); null — ещё не введена
    ShareIn:
      type: string
      pattern: '^\d{1,3}(\.\d{1,4})?$'
      description: 0…100, до 4 знаков после запятой; вне диапазона — 422 INVALID_SHARE
    Ref:
      type: object
      required: [id, name]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }

    DomainErrorOut:
      type: object
      required: [detail]
      properties:
        detail:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              enum:
                - NOT_FOUND
                - VERSION_NOT_EDITABLE
                - LOCK_REQUIRED
                - LOCKED_BY_OTHER
                - COMMENT_REQUIRED
                - INVALID_SHARE
            message: { type: string, description: Текст по-русски }
          additionalProperties: true

    GoodwillTableOut:
      type: object
      required: [version_id, goodwill_enabled, editable, read_only_reason, rows, totals]
      properties:
        version_id: { type: string, format: uuid }
        goodwill_enabled: { type: boolean }
        editable: { type: boolean }
        read_only_reason:
          type: [string, 'null']
          enum: [null, VERSION_NOT_EDITABLE, LOCK_REQUIRED, LOCKED_BY_OTHER]
        rows:
          type: array
          items: { $ref: '#/components/schemas/GoodwillRowOut' }
        totals: { $ref: '#/components/schemas/GoodwillTotalsOut' }

    GoodwillRowOut:
      type: object
      required:
        - head_legal_entity
        - subsidiary_legal_entity
        - ownership_share
        - financial_investment_amount
        - charter_capital_amount
        - additional_capital_amount
        - participation_amount
        - goodwill_amount
        - include_in_kfo
        - comment
        - updated_by
        - updated_at
      properties:
        head_legal_entity: { $ref: '#/components/schemas/Ref' }
        subsidiary_legal_entity: { $ref: '#/components/schemas/Ref' }
        ownership_share: { $ref: '#/components/schemas/Share' }
        financial_investment_amount: { $ref: '#/components/schemas/Money' }
        charter_capital_amount: { $ref: '#/components/schemas/Money' }
        additional_capital_amount: { $ref: '#/components/schemas/Money' }
        participation_amount: { $ref: '#/components/schemas/Money' }
        goodwill_amount: { $ref: '#/components/schemas/Money' }
        include_in_kfo: { type: boolean }
        comment: { type: [string, 'null'] }
        updated_by:
          oneOf:
            - $ref: '#/components/schemas/Ref'
            - type: 'null'
        updated_at: { type: [string, 'null'], format: date-time }

    GoodwillTotalsOut:
      type: object
      required: [financial_investment_amount, participation_amount, goodwill_amount, goodwill_in_kfo_amount]
      properties:
        financial_investment_amount: { $ref: '#/components/schemas/Money' }
        participation_amount: { $ref: '#/components/schemas/Money' }
        goodwill_amount: { $ref: '#/components/schemas/Money' }
        goodwill_in_kfo_amount:
          allOf: [{ $ref: '#/components/schemas/Money' }]
          description: Сумма goodwill_amount только по строкам include_in_kfo = true с положительным goodwill_amount

    GoodwillRowIn:
      type: object
      required: [ownership_share, include_in_kfo, comment]
      properties:
        ownership_share: { $ref: '#/components/schemas/ShareIn' }
        include_in_kfo: { type: boolean }
        comment:
          type: [string, 'null']
          maxLength: 1000
          description: Обязателен (непустой после обрезки), если include_in_kfo = true

    GoodwillSettingsIn:
      type: object
      required: [goodwill_enabled]
      properties:
        goodwill_enabled: { type: boolean }