IikoConnector: FIFO supplier settlement and supplier advances

1. Сначала изучи правила и условия агентов

До любой реализации прочитай в указанном порядке (пути от корня репозитория IikoConnector):

1. AGENTS.md
2. src/IikoConnector/AGENTS.md
3. docs/agent-rules/no-invention-and-clarification.md
4. docs/agent-rules/official-iiko-api-source.md
5. docs/agent-rules/iiko-connector-module-boundaries.md
6. src/IikoConnector/docs/iiko-connector-operating-map.md
7. src/IikoConnector/docs/iiko-methods.registry.yml
8. src/IikoConnector/docs/iiko-work-package-ledger.md
9. docs/integrations/iiko/iiko-connector-agent-guide.md, если файл существует
10. agent-manifest.yml
11. codegraph/manifest.yaml до структурных изменений API или DTO

При любой неясности сначала исследуй:

• research/iiko/ (extracted и server);
• src/IikoConnector/docs/iiko-support-matrix.md;
• docs/integrations/iiko/;
• релевантные материалы src/IikoConnector/docs/trace/;
• последние релевантные docs/iterations/*iiko*.

Режим выполнения:

• работай полностью автономно и одним непрерывным прогоном;
• последовательно выполняй микроитерации; формат каждой микроитерации строго: 1. Gherkin, затем 2. Код;
• не останавливайся между микроитерациями и после каждой запускай релевантные build/tests;
• следующая микроитерация учитывает уже добавленные feature-файлы, код, документацию и результаты предыдущих проверок;
• останавливайся только при существенном противоречии подтверждённых контрактов, которое нельзя безопасно разрешить fail-closed; в остальных случаях продолжай research/foundation и честно фиксируй неподтверждённую часть;
• не выдумывай RPC, REST endpoint, XML-поля или edition-specific поведение: любой mutation contract должен быть подтверждён официальным source либо реальной sanitized-трассой;
• credentials бери только из .ai-local/iiko-test-contours.env или process environment, никогда не проси и не логируй их;
• live mutation допустима только на явно настроенном безопасном тестовом контуре; при его отсутствии не имитируй success и зафиксируй evidence-backed blocker;
• используй Newtonsoft typed DTO; запрещены System.Text.Json, JObject, JToken и untyped JSON/XML trees как публичный контракт;
• все mutations требуют idempotency, audit evidence, строгого readback и запрета blind retry;
• ответы, документация и финальный отчёт — на русском.

2. Требования: что найти и что добавить

Цель исследования

Нужно source/trace-backed определить и, только если контракт подтверждён, реализовать публичный NuGet API для:

1. оплаты задолженности поставщика по одной или нескольким проведённым накладным;
2. выяснения, кто выполняет FIFO: Syrve или вызывающая система;
3. создания операции Advances to supplier на штатном счёте авансов поставщикам;
4. readback созданного аванса;
5. применения аванса к проведённой накладной, включая частичное применение;
6. отмены применения и сторно исходного аванса;
7. безопасного восстановления после неизвестного результата записи;
8. подтверждённого поведения RMS и CHAIN.

Не считать авансом обычную бездокументную оплату, локальный остаток или синтетический external id. Не объявлять операцию успешной без подтверждённой записи и readback.

Targeted inspection

До создания нового API найди:

• существующие supplier settlement/payment methods, DTO, XML renderers/parsers, clients, DI и options;
• поддержку Advances to supplier, supplier advance account, account/cash-flow references;
• document payment methods для incoming/outgoing invoice, service receipt/provision;
• idempotency key, request hash, external operation id и audit/evidence модели;
• readback, reversal/void/storno и unknown-write recovery;
• live harness и sanitized trace format;
• отличия RMS/CHAIN;
• public NuGet surface и уже существующие тестовые fixtures.

Если capability уже существует, документируй точный public API, DI/options и проверенный способ использования. Не создавай дубликат.

Обязательные исследовательские трассы

На безопасном тестовом контуре сними request/response и независимый readback для каждого сценария:

1. Частичная оплата: долг 300000, платёж 250000.
2. Точная оплата: долг 300000, платёж 300000.
3. Переплата: долг 300000, банковская сумма 350000, из них 300000 в погашение и 50000 в supplier advance.
4. Применение аванса: существующий аванс 50000, новая проведённая накладная 80000.
5. Частичное применение: существующий аванс 50000, применить 30000.
6. Отмена применения аванса.
7. Сторно аванса.
8. Повтор каждого mutation-вызова с тем же idempotency key.
9. Timeout/разрыв после возможной записи с обязательным readback до retry.
10. Те же применимые операции отдельно в RMS и CHAIN.

Для каждой операции сохрани в sanitized evidence:

• RPC method;
• endpoint;
• canonical rendered request XML;
• response XML;
• supplier id;
• document id;
• operation type;
• debit/credit account ids и их назначение;
• cash-flow article id и обязательность ДДС;
• знаки всех сумм;
• payment/operation date и timezone;
• обязательные и опциональные поля;
• external operation id;
• readback method, ожидаемое состояние и фактический результат;
• reversal/void/storno method и фактический readback после отмены;
• repeated-call behaviour;
• timeout/unknown-result behaviour;
• RMS behaviour;
• CHAIN behaviour.

Raw traces с credentials, cookies, токенами или production identifiers не коммить. В репозиторий попадают только sanitized fixtures/evidence и воспроизводимые выводы.

Вопросы, на которые evidence должен дать однозначный ответ

1. FIFO выполняет Syrve или вызывающая система?
2. Какое поле задаёт FIFO-порядок: due date, document date, posting date или другое?
3. Можно ли одной операцией закрыть несколько документов?
4. Можно ли одной атомарной операцией одновременно закрыть документы и создать advance?
5. Если требуется несколько operations, как выявить и восстановить частичный успех?
6. Как отличить supplier advance от кредиторской задолженности в readback?
7. Можно ли применить один advance к нескольким накладным и несколько advances к одной?
8. Как выполнить частичное применение?
9. Каковы правила отмены применения и сторно исходного аванса?
10. Какие idempotency guarantees даёт сервер и какой client key он принимает?
11. Как безопасно разрешить timeout после записи без слепого повтора?
12. Одинаковы ли contracts и accounting signs в RMS и CHAIN?

Микроитерации: сначала Gherkin, затем код

Используй существующую BDD-инфраструктуру; не создавай второй framework. Feature-сценарии должны быть исполнимыми и проверять rendered request, transport call count, response parsing, readback, external id, repeat behaviour и reversal evidence.

Микроитерация 1 — существующий document settlement:

Feature: Оплата поставщика по FIFO

Scenario: Частичная оплата сохраняет остаток долга
Scenario: Точная оплата закрывает долг
Scenario: FIFO закрывает несколько проведённых документов в подтверждённом порядке
Scenario: Непроведённый или удалённый документ не принимается
Scenario: Повторный idempotent вызов не создаёт вторую оплату

После Gherkin расширяй код только на основе существующего или подтверждённого document-payment контракта. Если server-side FIFO не подтверждён, не добавляй supplier-level write.

Микроитерация 2 — создание и readback аванса:

Feature: Создание аванса поставщику

Scenario: Переплата создаёт отдельную операцию Advances to supplier
Scenario: Аванс использует подтверждённый supplier advance account
Scenario: Успешный response без readback не считается завершённой операцией

Feature: Readback аванса

Scenario: Readback находит аванс по подтверждённому external operation id
Scenario: Readback подтверждает сумму, знак, поставщика, счёт и дату
Scenario: Отсутствующий или неоднозначный readback оставляет результат неизвестным

До кода должны существовать реальные create/readback traces. Public API — typed request/result, без raw tree; ExternalAdvanceId появляется только из подтверждённого ответа/readback.

Микроитерация 3 — применение:

Feature: Применение аванса к накладной

Scenario: Аванс применяется только к проведённой неудалённой накладной
Scenario: Применение уменьшает аванс и долг накладной на одну сумму
Scenario: Readback подтверждает обе стороны операции

Feature: Частичное применение аванса

Scenario: Из аванса 50000 применяется 30000
Scenario: После применения остаётся подтверждённый аванс 20000
Scenario: Повтор не применяет те же 30000 второй раз

До кода должны существовать apply/readback traces. Нельзя выводить применение из локальной арифметики без серверного evidence.

Микроитерация 4 — отмена и сторно:

Feature: Отмена применения аванса

Scenario: Отмена восстанавливает подтверждённые остатки аванса и накладной
Scenario: Повтор отмены идемпотентен

Feature: Сторно аванса

Scenario: Неприменённый аванс сторнируется подтверждённым методом
Scenario: Сторно применённого аванса следует подтверждённой последовательности
Scenario: Readback подтверждает результат сторно

Для каждого mutation обязателен полный render → response parse → independent readback → reversal contract.

Микроитерация 5 — editions и неизвестный результат:

Feature: Идемпотентность операций аванса

Scenario: Повтор create с тем же ключом не создаёт второй аванс
Scenario: Повтор apply с тем же ключом не применяет аванс второй раз

Feature: Поведение RMS и CHAIN

Scenario Outline: Подтверждённая операция работает на edition
  Examples:
    | edition |
    | RMS     |
    | CHAIN   |

Feature: Неизвестный результат записи

Scenario: Timeout после create требует readback до retry
Scenario: Неоднозначный readback запрещает повторную mutation
Scenario: Частичный успех группы операций не повторяет подтверждённую часть

После каждой микроитерации обновляй registry/support matrix/work-package ledger/trace docs, запускай релевантные tests и build. Не ослабляй проверки ради suite.

Желаемый public contract — только после подтверждения

Сначала выведи фактические сигнатуры из evidence и conventions репозитория. Public NuGet surface должен как минимум предоставлять typed:

• request/result для document settlement и, если подтверждено, multi-document/FIFO settlement;
• create supplier advance request/result;
• supplier advance readback query/result;
• apply supplier advance request/result;
• reverse application и reverse advance request/result;
• явные outcomes Succeeded, Failed, WriteOutcomeUnknown;
• stable idempotency key/request hash/external operation id;
• edition-aware capability result вместо искусственного success.

Не добавляй предположительные сигнатуры только ради соответствия этому outline.

Acceptance checklist

• [ ] Все заявленные methods и XML shapes подтверждены source или sanitized live trace.
• [ ] Для каждого mutation есть исполнимый render/parse/readback/reversal тест.
• [ ] Exact/partial/overpayment/apply/partial-apply/cancel/storno сценарии имеют конкретные assertions.
• [ ] Непроведённые, удалённые и unknown-state документы блокируются fail-closed.
• [ ] Timeout не приводит к blind retry.
• [ ] Идемпотентность и частичный успех доказаны transport-call-count/readback assertions.
• [ ] RMS и CHAIN либо подтверждены отдельно, либо capability честно сообщает unsupported/unknown.
• [ ] Public API и DI/options описаны.
• [ ] Registry, support matrix, ledger и sanitized evidence обновлены.
• [ ] Релевантные tests и dotnet build зелёные.
• [ ] dotnet pack создаёт пакеты в artifacts/nuget.

3. Финал: отчёт, commit, push

По окончании:

1. Выдай финальный отчёт на русском: targeted inspection, найденные contracts, evidence для каждой операции, реализованные API/DTO/parsers, Gherkin/tests, RMS/CHAIN, версия package, честные blockers и неподтверждённые поля.
2. Не заявляй успешную поддержку advance, apply или reversal, если отсутствует реальная write + independent readback + reversal evidence.
3. Выполни git commit с осмысленным сообщением по сути изменений, без упоминаний ИИ/агентов и без Co-authored-by.
4. Выполни git push в remote IikoConnector.
5. Definition of Done: зелёные релевантные тесты и dotnet pack в artifacts/nuget, либо честный documented blocker с evidence, без придуманного transport contract.