arm-ka-docs/dev/api-contract-goodwill.md

# Контракт API таблицы гудвилла (AURORA-1543 / AURORA-1544)

Черновик контракта для бэкенда (AURORA-1543, Цыганков) и фронта (AURORA-1544, Голов) — по аналогии с
`dev/api-contract-corrections.md`: фронт строит экран по контракту на фейковых данных, не дожидаясь бэкенда, подключение
к реальным ручкам — потом. Машиночитаемая копия — `dev/api-contract-goodwill.openapi.yaml`; при расхождении двух файлов
правится тот, что ошибся, и оба держатся одинаковыми.

Источники, в порядке приоритета:
1. **AURORA-1369** (решение методологов, срок 02.11.2026) — формула ещё не подтверждена, см. §5 «Открытые вопросы». Пока
   не закрыта, бэкенд не считает по-настоящему — но контракт (форма ответа, поля, эндпоинты) этим не затронут: методологи
   могут поменять *формулу* (входит ли 1350, источник УК), а не *набор полей* (поля `charter_capital_amount` /
   `additional_capital_amount` под обе ветки уже есть в DBML).
2. `05-domain-rules.md` §8 «Гудвилл» — текущий рабочий алгоритм (допущения OQ-10, OQ-37).
3. DBML v5.23, `Table goodwill`, `Table kfo_result_line` (`line_code = 'GOODWILL'`), `consolidation_version.goodwill_enabled`.
4. Макет: `[31-03]` «Гудвилл» (таблица, режим «Редактировать»), `[31-04]` «КФО» (строка «В т.ч. Гудвилл» под 1170).
5. ТЗ 6.7, Прил. 3 п. 2, Прил. 8 — только там, где остальное молчит.

## 1. Общее

Всё как в `dev/api-contract-slice-4.md` §1 и `dev/api-contract-corrections.md` §1:
- префикс `/api/v1`, `Authorization: Bearer <JWT>`;
- чтение — право `CONSOLIDATION_VIEW`, правки — `CONSOLIDATION_EDIT`;
- версия вне видимости — 404 `NOT_FOUND`, как несуществующая;
- доменные ошибки — `{"detail": {"code", "message", ...}}`, 422 валидации тела — массив pydantic;
- **деньги — строки с двумя знаками** (`"1000000.00"`), всегда в **рублях**; перевод в тыс. руб. — на фронте;
- порядок проверок правок: право (403) → видимость (404) → версия редактируема (409) → операция; коды — те же, что везде:
  409 `VERSION_NOT_EDITABLE`, `LOCK_REQUIRED`, `LOCKED_BY_OTHER`. Фронт читает `editable` / `read_only_reason` из ответа
  таблицы, правило не повторяет.

## 2. Понятия

- **Головная организация периметра (ГО)** — член версии консолидации с `is_head_entity = true` (как в `VersionCard.members[]`,
  `dev/api-contract-slice-4.md` §3). **Дочерняя организация (ДО)** — любой другой член периметра. Таблица гудвилла — по
  одной строке на каждую пару (ГО, ДО); строки не создаются и не удаляются пользователем, их состав определяется
  составом периметра (`PUT …/members`) на момент запроса. **Если в периметре несколько `is_head_entity`** — строки
  считаются для каждой ГО отдельно (как для независимых голов); на реальных данных такого пока не встречалось —
  ASSUMPTION, уточнить при первом расхождении.
- **Фондовые вложения (`financial_investment_amount`, FV)** — `Σ closing_debit` счёта `58.01` ГО по контрагенту ДО
  (сводная ОСВ версии). Может быть `0.00` — строка всё равно показывается (полный список ДО периметра под каждой ГО,
  как в макете `[31-03]`).
- **Уставный капитал ДО (`charter_capital_amount`, УК)** — стр. `1310` ББ ДО на отчётную дату; при наличии ОСВ ДО —
  `Кт 80 + Кт 83`, иначе `1310` из формы (§8 domain-rules, уточняет первую часть OQ-10). **Добавочный капитал
  (`additional_capital_amount`)** — стр. `1350` ББ ДО, считается и хранится всегда, независимо от того, участвует ли
  в формуле (см. OQ-10 ниже).
- **Доля владения (`ownership_share`)** — ручной ввод аналитика, % (`numeric(7,4)`); единственное обязательное поле
  правки наряду с `comment`.
- **Доля участия (`participation_amount`)** = `(charter_capital_amount [+ additional_capital_amount, если решение
  методологов это подтвердит]) × ownership_share / 100`.
- **Гудвилл (`goodwill_amount`)** = `financial_investment_amount − participation_amount`; может быть отрицательным.
- **Учёт в КФО (`include_in_kfo`)** — чекбокс «Учёт в отчёте» строки (макет `[31-03]`, с «Выделить все» по ГО на
  фронте — пакетное действие фронта, не отдельная ручка). Комментарий обязателен **только** когда `include_in_kfo = true`
  (ТЗ 6.7). Положительная сумма отмеченных строк уходит в `kfo_result_line` с `line_code = 'GOODWILL'`
  (раздел I КФО, допущение OQ-37) — расчёт и запись при построении результата КФО, не в этом контракте.
- **Признак расчёта гудвилла (`goodwill_enabled`)** — переключатель версии (`consolidation_version.goodwill_enabled`,
  решено OQ-27: живёт на вкладке «Гудвилл», не в модалке создания). Сейчас в контракте нет ручки, которая бы его
  выставляла (только чтение через `VersionCard`, `dev/api-contract-slice-4.md`) — добавляется здесь (§3.2).
  Выключен — таблица показывается как есть (доли и комментарии не теряются), но ничего не уходит в КФО.

## 3. Эндпоинты

| Метод и путь | Право | Запрос | Ответ | Ошибки |
|---|---|---|---|---|
| `GET /consolidations/versions/{version_id}/goodwill` | VIEW | — | 200 `GoodwillTableOut` | 404 `NOT_FOUND` |
| `PUT /consolidations/versions/{version_id}/goodwill-settings` | EDIT | `GoodwillSettingsIn` | 200 `GoodwillTableOut` | 404, 409 правок версии |
| `PUT /consolidations/versions/{version_id}/goodwill/{head_legal_entity_id}/{subsidiary_legal_entity_id}` | EDIT | `GoodwillRowIn` | 200 `GoodwillRowOut` | 404 `NOT_FOUND` (версия или пара не из периметра), 409 правок версии, 422 `COMMENT_REQUIRED`, 422 `INVALID_SHARE` |
| `GET /consolidations/versions/{version_id}/goodwill/export` | VIEW | — | файл xlsx | 404 `NOT_FOUND` |

### 3.1 `GET …/goodwill` — таблица

Все строки одним ответом (пар — единицы, не десятки; без страниц). Порядок: по имени ГО, внутри — по имени ДО.
Группировку по ГО и подсчёт «Выделить все» делает фронт. Пустой периметр (только ГО, без ДО) — `rows = []`, это не ошибка.

### 3.2 `PUT …/goodwill-settings` — переключатель версии

Меняет `consolidation_version.goodwill_enabled`. Аудит — новое действие в `audit_action` (например,
`GOODWILL_ENABLED_CHANGE`), результат КФО помечается устаревшим при любом изменении значения (как в AURORA-1417).
Выключение не трогает сохранённые строки (`ownership_share`, `comment`, `include_in_kfo` остаются).

### 3.3 `PUT …/goodwill/{head_legal_entity_id}/{subsidiary_legal_entity_id}` — сохранить строку

Сохраняет **все поля строки целиком** (как в `PUT …/corrections/aggregates/…` — текущие `ownership_share`,
`include_in_kfo` и `comment` приходят каждый раз, частичного `PATCH` нет).

- `head_legal_entity_id` должен быть членом периметра с `is_head_entity = true`, `subsidiary_legal_entity_id` — любым
  другим членом периметра; иначе 404 `NOT_FOUND` (пары не существует).
- `ownership_share` — строка `0`…`100`, до 4 знаков после запятой (`numeric(7,4)`); вне диапазона или больше 4 знаков —
  422 `INVALID_SHARE`.
- `comment` обязателен, если `include_in_kfo = true`; пустой после обрезки в этом случае — 422 `COMMENT_REQUIRED`
  (как `COMMENT_REQUIRED` в контракте корректировок); не длиннее 1000 символов. При `include_in_kfo = false` комментарий
  необязателен и может быть `null`.
- `financial_investment_amount`, `charter_capital_amount`, `additional_capital_amount`, `participation_amount`,
  `goodwill_amount` в тело **не входят** — это вычисляемые поля, пересчитываются сервером из текущей ОСВ версии при
  каждом ответе, в запросе их нет.
- Аудит `GOODWILL_ROW_EDIT` (поле нужно добавить в `audit_action`, как `CORRECTION_*` для корректировок) с `before`/`after`;
  результат КФО помечается устаревшим.

Ответ — пересчитанная строка (а не вся таблица — в отличие от корректировок, строки гудвилла друг на друга не влияют).

### 3.4 `GET …/export` — xlsx

Таблица гудвилла одним листом, группировка по ГО, итоговая строка «Всего» (макет `[31-03]`). Имя файла —
`Гудвилл_<название ГК>_<год>_<квартал>.xlsx` в `Content-Disposition` (как в экспорте корректировок). Аудит `EXPORT`.

## 4. Схемы

Поля без `?` есть всегда; `null` указан явно.

**`GoodwillTableOut`**
```
version_id            uuid
goodwill_enabled       bool
editable              bool
read_only_reason      null | "VERSION_NOT_EDITABLE" | "LOCK_REQUIRED" | "LOCKED_BY_OTHER"
rows[]                GoodwillRowOut
totals                GoodwillTotalsOut
```

**`GoodwillRowOut`**
```
head_legal_entity            Ref            {id, name}
subsidiary_legal_entity      Ref
ownership_share               share | null    % 4 знака; null — ещё не введена
financial_investment_amount  money
charter_capital_amount        money
additional_capital_amount     money
participation_amount          money
goodwill_amount                money          может быть отрицательным
include_in_kfo                bool
comment                        string | null
updated_by                    Ref | null
updated_at                     datetime | null
```

**`GoodwillTotalsOut`** — сумма по всем строкам ответа: `{financial_investment_amount, participation_amount,
goodwill_amount}`, плюс `goodwill_in_kfo_amount` — сумма `goodwill_amount` только по строкам с `include_in_kfo = true`
и положительным `goodwill_amount` (то, что реально уйдёт в `kfo_result_line.line_code = 'GOODWILL'`).

**`GoodwillRowIn`** `{ownership_share (share-строка 0…100), include_in_kfo (bool), comment (string | null, обязателен
при include_in_kfo = true, ≤ 1000 символов)}`.

**`GoodwillSettingsIn`** `{goodwill_enabled (bool)}`.

## 5. Открытые вопросы (AURORA-1369, срок 02.11.2026)

- **OQ-10** — входит ли стр. 1350 (добавочный капитал) в базу участия. Допущение сейчас: **нет**, `participation_amount`
  считается только от `charter_capital_amount`; `additional_capital_amount` хранится и показывается в таблице (колонка
  есть и в DBML, и на фронте — макет её не показывает явно, но поле в `goodwill` есть с пометкой ADD), но не входит в
  формулу. Если методологи подтвердят, что 1350 нужен — меняется только формула на бэкенде, контракт не меняется.
- **OQ-37** — код строки «Гудвилл» в результате КФО: служебный `GOODWILL` (как в DBML, принято этим контрактом) или
  `1105` как в распознанной форме ББ (ФСБУ 4/2023). Контракта это не касается напрямую (он про таблицу `goodwill`, не
  про `kfo_result_line`), но влияет на отдельную задачу построения КФО — не блокирует 1543/1544.
- Несколько `is_head_entity` в одном периметре — не встречалось на фикстурах, поведение не проверено отдельно.

**Фронт (AURORA-1544) ничего из этого не ждёт** — строит экран по схемам §4 на фейковых данных; поля не меняются от
исхода открытых вопросов, меняются только числа внутри них.

## 6. Пример

`GET /api/v1/consolidations/versions/7b…/goodwill` (сокращено):

```json
{
  "version_id": "7b1c…",
  "goodwill_enabled": true,
  "editable": true,
  "read_only_reason": null,
  "rows": [
    {
      "head_legal_entity": {"id": "a…", "name": "АО «Русский бисквит»"},
      "subsidiary_legal_entity": {"id": "b…", "name": "ООО «Пекарня Счастливочная»"},
      "ownership_share": "100.0000",
      "financial_investment_amount": "5000000.00",
      "charter_capital_amount": "4500000.00",
      "additional_capital_amount": "0.00",
      "participation_amount": "4500000.00",
      "goodwill_amount": "500000.00",
      "include_in_kfo": true,
      "comment": "Доля подтверждена уставом от 01.01.2024",
      "updated_by": {"id": "u…", "name": "Иванов И. И."},
      "updated_at": "2026-10-30T12:00:00+03:00"
    }
  ],
  "totals": {
    "financial_investment_amount": "5000000.00",
    "participation_amount": "4500000.00",
    "goodwill_amount": "500000.00",
    "goodwill_in_kfo_amount": "500000.00"
  }
}
```