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

Контракт таблицы гудвилла версии консолидации — по факту реализации arm-core (#222, OpenSpec change `goodwill-table`).
Машиночитаемая копия — `dev/api-contract-goodwill.openapi.yaml`: она выгружена из `app.openapi()` и сверяется с
приложением тестом `arm-core/api/tests/test_goodwill_contract.py`. Если файлы расходятся, прав код, а оба файла
правятся вслед за ним.

Источники, в порядке приоритета:
1. **DOC-259025 «Гудвилл»** (вики аналитики, версия 03.11.2026, Лысенко) — пары, жизненный цикл строк, формулы, итоги,
   проверки ввода.
2. `05-domain-rules.md` §8 «Гудвилл» — выжимка того же с решениями по допущениям.
3. DBML v5.24: `Table goodwill`, `consolidation_version.goodwill_enabled`.
4. Макет `[31-03]` «Гудвилл» (таблица, режим «Редактировать»).

## 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"`) или `null`; `null` — «не рассчитано», а не ноль.
  Перевод в тыс./млн руб. — на фронте, после суммирования;
- **доля владения — строка с двумя знаками** (`"80.00"`) или `null`;
- порядок проверок правок: право (403) → видимость (404) → версия редактируема (409 `VERSION_NOT_EDITABLE`,
  `LOCK_REQUIRED`, `LOCKED_BY_OTHER`) → операция. Фронт берёт `editable` и `read_only_reason` из ответа таблицы и правило
  сам не повторяет; у пользователя без `CONSOLIDATION_EDIT` — `read_only_reason = "VERSION_NOT_EDITABLE"`.

## 2. Понятия

- **Пара ГО → ДО.** ГО — компания периметра, у которой в сводной ОСВ версии есть строки счёта `58.01` или его потомков
  (по `chart_of_account.parent_id`) с сопоставленным контрагентом из периметра; этот контрагент — ДО. Признак
  `is_head_entity` **не используется**: одна компания может быть ГО в одном блоке и ДО в другом, встречные направления —
  разные пары. Пустой контрагент, вложение в себя и контрагент вне периметра пару не дают. Ручного добавления пар нет.
- **Финансовые вложения (`financial_investment_amount`, ФВ)** — сумма заполненных `closing_debit` подходящих строк
  пары; ФВ = 0 — пары нет.
- **«Нет вложений» (`has_investments = false`).** Сохранённая пара, которая больше не находится (замена ОСВ, нулевое
  сальдо, компания вышла из периметра). Строка остаётся с сохранёнными долей, комментарием и галочкой, все денежные поля
  — `null`, в итоги и КФО не входит. Повторное появление пары восстанавливает расчёт по текущим данным.
- **Уставный капитал ДО (`charter_capital_amount`, УК)** — стр. `1310` подтверждённого ББ ДО, привязанного к версии,
  по колонке **конца отчётного квартала** (не по `is_current`), в рублях: единицы формы читаются словарём единиц
  `arm_statements` («тыс.руб.», «в тысячах рублей» → тыс. руб.). Повторы кода 1310 суммируются. Ноль — допустимое значение.
  Нет ББ, строки 1310 или колонки даты, единицы не распознаны — `null` и предупреждение `CAPITAL_SOURCE_MISSING`;
  у ДО несколько подходящих ББ — `null` и `CAPITAL_SOURCE_AMBIGUOUS`.
- **Добавочный капитал (`additional_capital_amount`)** — стр. `1350` того же ББ, справочно; в формулу не входит
  (ASSUMPTION OQ-10).
- **Доля владения (`ownership_share`)** — ручной ввод, % от `0` до `100`, не больше двух знаков после запятой.
- **Доля участия (`participation_amount`, P)** = `round(УК × доля / 100, 2)` (`ROUND_HALF_UP`), **гудвилл
  (`goodwill_amount`, G)** = `ФВ − P`, может быть отрицательным и нулевым. P и G считаются **только у действующей
  отмеченной строки** (`include_in_kfo = true`) с заполненными долей и УК, иначе `null`.
- **Учёт в отчёте (`include_in_kfo`)** — галочка строки. У отмеченной действующей строки обязательны доля и непустой
  комментарий. Снятие галочки не стирает долю и комментарий.
- **Признак учёта гудвилла (`goodwill_enabled`)** — переключатель версии (решение OQ-27: на вкладке «Гудвилл», не в
  модалке создания). Выключен — таблица и ручной ввод не меняются, но в КФО ничего не уходит
  (`goodwill_in_kfo_amount = "0.00"`).
- **Предупреждения (`warnings[]`)** — `{code, message}`, не блокируют сохранение:
  `CAPITAL_SOURCE_MISSING`, `CAPITAL_SOURCE_AMBIGUOUS` (см. УК), `OWNERSHIP_TOTAL_EXCEEDED` — сумма заполненных долей
  действующих пар разных ГО в одной ДО больше 100 % (показывается у всех строк этой ДО).

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

| Метод и путь | Право | Запрос | Ответ | Ошибки |
|---|---|---|---|---|
| `GET /consolidations/versions/{version_id}/goodwill` | VIEW | — | 200 `GoodwillTableOut` | 404 `NOT_FOUND` |
| `PUT /consolidations/versions/{version_id}/goodwill` | EDIT | `GoodwillBatchIn` | 200 `GoodwillTableOut` | 404 `NOT_FOUND` (версия или пара), 409 правок версии, 422 `INVALID_SHARE`, `COMMENT_REQUIRED`, `MONEY_OUT_OF_RANGE`, `DUPLICATE_ROW`, 422 валидации тела |
| `PUT /consolidations/versions/{version_id}/goodwill-settings` | EDIT | `GoodwillSettingsIn` | 200 `GoodwillTableOut` | 404, 409 правок версии |
| `GET /consolidations/versions/{version_id}/goodwill/export?sign=all\|positive\|negative\|zero` | VIEW | — | файл xlsx | 404 `NOT_FOUND`, 422 неизвестный `sign` |

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

Все строки одним ответом, без страниц. Порядок строк — имя ГО, имя ДО, затем id; `groups` — в том же порядке ГО.
Чтение ничего не пишет (записи `goodwill` создаются только сохранением). Нет пар и сохранённых строк — `rows = []`,
`groups = []`, итоги `"0.00"`.

### 3.2 `PUT …/goodwill` — сохранить набор строк

Тело — изменённые аналитиком строки целиком (`ownership_share`, `include_in_kfo`, `comment` каждой строки приходят
каждый раз). **Пакет сохраняется в одной транзакции**: сначала проверяются все строки, ошибка любой — ответ с её ключом
(`detail.head_legal_entity_id`, `detail.subsidiary_legal_entity_id`) и ничего не сохраняется.

- Пара должна быть в текущей таблице (действующая или «Нет вложений»), иначе 404 `NOT_FOUND` с ключом пары.
- Одна пара дважды в пакете — 422 `DUPLICATE_ROW`.
- `ownership_share` — `null` или строка `0`…`100`, не больше двух знаков после запятой, запятая или точка
  (`"80,5"` = `"80.5"`). Лишние знаки, отрицательные, экспонента — 422 `INVALID_SHARE` (без округления). У отмеченной
  строки доля обязательна — `null` даёт `INVALID_SHARE`.
- `comment` — до 1000 символов; у отмеченной строки пустой после обрезки — 422 `COMMENT_REQUIRED`.
- У строки «Нет вложений» `null` в доле или комментарии не стирает сохранённое значение.
- Строка, ввод которой совпадает с сохранённым (или для пары без записи — с умолчанием «не отмечена, доли и комментария
  нет»), не перезаписывается: `updated_by/updated_at` не меняются, аудита нет. Поэтому фронт может отправлять весь набор
  отмеченных строк, но лучше — только изменённые.
- У изменённой действующей строки вместе с вводом сохраняется снимок сумм (ФВ, УК, 1350, P, G); сумма вне
  `numeric(18,2)` — 422 `MONEY_OUT_OF_RANGE`.
- Аудит — `GOODWILL_EDIT` на каждую изменённую строку (`object_type = goodwill`, `before`/`after` — строка ответа).

Ответ — пересчитанная таблица целиком (строки, итоги по ГО и общие).

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

Меняет `consolidation_version.goodwill_enabled`. Повтор прежнего значения ничего не пишет. Изменение — аудит
`GOODWILL_EDIT` (`object_type = consolidation_version`, `changed_field = goodwill_enabled`). Ручной ввод строк не
трогается.

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

Лист «Гудвилл»: восемь колонок экранной таблицы (Учёт в отчёте, Наименование дочерней организации, Доля владения,
Фондовые вложения головной организации, Доля участия ГО в УК, Уставный капитал, Гудвилл (+/−), Комментарий), блок на
каждую ГО со строкой «Всего», в конце — «Итого по листу». Деньги — в рублях, `null` — пустая ячейка; у строки «Нет
вложений» в колонке ФВ — текст «Нет вложений». `sign` оставляет
строки с гудвиллом нужного знака (нерассчитанные в фильтры по знаку не попадают), итоги остаются по полному составу.
Выгружается последнее сохранённое состояние. Имя — `Гудвилл_<ГК>_<год>_<квартал>.xlsx` в `Content-Disposition`
(`filename*`). Аудит `EXPORT` с `{report: "goodwill", rows: <число строк в файле>}`.

## 4. Схемы

Поля без `?` есть всегда; `null` указан явно. `money` — строка с двумя знаками, `share` — строка с двумя знаками.

**`GoodwillTableOut`**
```
version_id         uuid
goodwill_enabled   bool
editable           bool
read_only_reason   null | "VERSION_NOT_EDITABLE" | "LOCK_REQUIRED" | "LOCKED_BY_OTHER"
rows[]             GoodwillRowOut
groups[]           GoodwillGroupOut     итог «Всего» по каждой ГО
totals             GoodwillTotalsOut    «Итого по листу»
```

**`GoodwillRowOut`**
```
head_legal_entity            Ref {id, name}
subsidiary_legal_entity      Ref
ownership_share              share | null
financial_investment_amount  money | null    null у «Нет вложений»
charter_capital_amount       money | null    null — нет однозначного 1310 или «Нет вложений»
additional_capital_amount    money | null    справочно, в формулу не входит
participation_amount         money | null    только у действующей отмеченной строки
goodwill_amount              money | null    может быть < 0 и = 0
include_in_kfo               bool
comment                      string | null
has_investments              bool
warnings[]                   {code, message}
updated_by                   Ref | null
updated_at                   datetime | null
```

**`GoodwillGroupOut`** `{head_legal_entity: Ref, totals: GoodwillTotalsOut}`.

**`GoodwillTotalsOut`** — по действующим строкам (без «Нет вложений»):
```
financial_investment_amount  money   все действующие строки, независимо от галочки
charter_capital_amount       money   все действующие строки (УК одной ДО у нескольких ГО входит несколько раз)
participation_amount         money   только отмеченные
goodwill_amount              money   только отмеченные, отрицательные и нулевые тоже
goodwill_in_kfo_amount       money   положительные G отмеченных строк с долей и комментарием; 0.00 при goodwill_enabled = false
```

**`GoodwillBatchIn`** `{rows: GoodwillRowKeyIn[]}` (минимум одна строка).

**`GoodwillRowKeyIn`** `{head_legal_entity_id: uuid, subsidiary_legal_entity_id: uuid, ownership_share: string | null,
include_in_kfo: bool, comment: string | null (≤ 1000)}`.

**`GoodwillSettingsIn`** `{goodwill_enabled: bool}`.

## 5. Граница этапа и открытые вопросы

- **КФО.** Применение гудвилла в КФО (1170 ГО − ФВ, 1310 ДО − P, строка `GOODWILL` + G), исключение обычного ББ-2 по
  паре, пометка результата КФО устаревшим и фиксация при VERIFIED — задача AURORA-1546, этим API не делается.
- **OQ-10** — 1350 в базу участия не входит (DOC-259025 §6: «Для УК используется 1310»), колонка — справочно.
- **OQ-37** — служебный код `GOODWILL` для строки КФО (DOC-259025 §7).

## 6. Что изменилось против черновика 30.10

- ГО — по фактическим вложениям 58.01, а не по `is_head_entity`; строк «все ДО под каждой ГО» больше нет.
- Новые поля строки: `has_investments`, `warnings`; УК, 1350, P, G и ФВ — nullable.
- Новые поля ответа: `groups[]`, `totals.charter_capital_amount`.
- P и G — только у отмеченных строк; итоги P и G — по отмеченным.
- Доля — два знака, а не четыре.
- Построчный `PUT …/goodwill/{head}/{sub}` заменён пакетным `PUT …/goodwill` (одна транзакция, ответ — вся таблица).
- У экспорта — параметр `sign`.

## 7. Пример

`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": "80.00",
      "financial_investment_amount": "180000.00",
      "charter_capital_amount": "100000.00",
      "additional_capital_amount": "0.00",
      "participation_amount": "80000.00",
      "goodwill_amount": "100000.00",
      "include_in_kfo": true,
      "comment": "Доля подтверждена уставом",
      "has_investments": true,
      "warnings": [],
      "updated_by": {"id": "u…", "name": "Иванов И. И."},
      "updated_at": "2026-11-06T12:00:00Z"
    },
    {
      "head_legal_entity": {"id": "a…", "name": "Альфа"},
      "subsidiary_legal_entity": {"id": "c…", "name": "Гамма"},
      "ownership_share": "80.00",
      "financial_investment_amount": "50000.00",
      "charter_capital_amount": "100000.00",
      "additional_capital_amount": null,
      "participation_amount": "80000.00",
      "goodwill_amount": "-30000.00",
      "include_in_kfo": true,
      "comment": "Доля подтверждена уставом",
      "has_investments": true,
      "warnings": [],
      "updated_by": null,
      "updated_at": null
    }
  ],
  "groups": [
    {
      "head_legal_entity": {"id": "a…", "name": "Альфа"},
      "totals": {
        "financial_investment_amount": "230000.00",
        "charter_capital_amount": "200000.00",
        "participation_amount": "160000.00",
        "goodwill_amount": "70000.00",
        "goodwill_in_kfo_amount": "100000.00"
      }
    }
  ],
  "totals": {
    "financial_investment_amount": "230000.00",
    "charter_capital_amount": "200000.00",
    "participation_amount": "160000.00",
    "goodwill_amount": "70000.00",
    "goodwill_in_kfo_amount": "100000.00"
  }
}
```

`PUT /api/v1/consolidations/versions/7b…/goodwill`:

```json
{"rows": [
  {"head_legal_entity_id": "a…", "subsidiary_legal_entity_id": "b…", "ownership_share": "80", "include_in_kfo": true, "comment": "Доля подтверждена уставом"},
  {"head_legal_entity_id": "a…", "subsidiary_legal_entity_id": "d…", "ownership_share": null, "include_in_kfo": false, "comment": null}
]}
```

Ошибка строки:

```json
{"detail": {"code": "COMMENT_REQUIRED", "message": "Укажите комментарий",
            "head_legal_entity_id": "a…", "subsidiary_legal_entity_id": "b…"}}
```