31b8e41674
Черновик для параллельной разработки бэкенда и фронта, по аналогии с api-contract-corrections: фронт строит экран на фейковых данных, не дожидаясь методологов (AURORA-1369, срок 02.11) и бэкенда. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
279 lines
11 KiB
YAML
279 lines
11 KiB
YAML
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 }
|