# ─────────────────────────────────────────────────────────────────────────────
# Стандарт «Возврат паевого взноса» — деньгами, через целевую потребительскую
# программу «Цифровой Кошелёк» (SHARE_FUND_PAY).
#
# Четырёхактовый процесс с одной авторизацией советом. Запись заявки живёт в
# таблице `withdraws` от создания до выплаты или отказа. На подаче заявки сумма
# переводится в кошелёк-резерв (WITHDRAW_PENDING, w.wal.wpend). На закрывающем
# действии completewthd срабатывает операция o.wal.wthcpl — сжигание суммы из
# резерва (BURN w.wal.wpend): деньги уходят из системы пайщику банковским
# переводом, получателя на цепи нет.
#
# Источники правды в коде:
#   • cpp/wallet/wallet.hpp                                 — actions
#   • cpp/wallet/src/withdraw/{createwthd,authwthd,completewthd,declinewthd}.cpp
#   • cpp/lib/domain/table_wallet_withdraws.hpp             — entity withdraws
#   • cpp/lib/core/ledger2/operations.hpp                   — o.wal.wthcpl
#   • cpp/lib/core/ledger2/processes.hpp                    — processes::wallet::WITHDRAW
# ─────────────────────────────────────────────────────────────────────────────

# ── Секция 1. Паспорт ───────────────────────────────────────────────────────
process_type: p.wal.wthdrw
id: public_wallet_withdraw_process
title: Возврат паевого взноса
slug: withdraw
status: proposed
contract: wallet
summary: >
  Пайщик получает обратно ранее внесённый паевой взнос деньгами. Заявку
  авторизует совет, кассир подтверждает выплату через Gateway.
purpose: >
  «Возврат паевого взноса» — пайщик получает обратно ранее внесённые
  деньги. Заявку рассматривает совет, после авторизации выплата
  отправляется через кассира. Это обратный процесс к «Внесению паевого
  взноса».
roles:
  - contributor
  - soviet
  - gateway_operator

# ── Секция 2. Действия контракта ────────────────────────────────────────────
actions:
  - name: wallet::createwthd
    human: Подать заявление
    actor: contributor
    role: opener
    purpose: >
      Пайщик создаёт заявку на возврат паевого взноса. Контракт переводит
      сумму с кошелька SHARE_FUND_PAY в кошелёк-резерв WITHDRAW_PENDING и
      создаёт повестку в совете о возврате с callback'ом авторизации.
  - name: wallet::authwthd
    human: Авторизовать выплату
    actor: soviet
    role: progress
    purpose: >
      Совет авторизует выплату единым решением: контракт переводит заявку
      в статус `authorized` и отправляет в Gateway исходящий платёж с
      callback'ами completewthd / declinewthd.
  - name: wallet::completewthd
    human: Подтвердить выплату
    actor: gateway_operator
    role: closer
    purpose: >
      Gateway подтвердил списание средств в пользу пайщика. Это закрывающее
      действие: применяется операция o.wal.wthcpl (BURN w.wal.wpend)
      — сумма из резерва сжигается, в бухгалтерии проходит обратная
      проводка Дт 80 / Кт 51. Запись заявки удаляется.
  - name: wallet::declinewthd
    human: Отклонить
    actor: soviet
    role: reject
    purpose: >
      Отказ на любом из этапов до выплаты. Сумма возвращается из резерва на
      кошелёк пайщика (o.wal.wthdec: WITHDRAW_PENDING → SHARE_FUND_PAY),
      запись заявки удаляется.

# ── Секция 3. Граф состояний ────────────────────────────────────────────────
entity: wallet::withdraw
entity_human: Заявка на возврат
entity_source: cpp/wallet/src/withdraw/

states:
  - name: pending
    human: Ожидает решения совета
    description: >
      Заявка создана, сумма переведена в кошелёк-резерв (SHARE_FUND_PAY →
      WITHDRAW_PENDING), повестка отправлена в совет.
    kind: normal
  - name: authorized
    human: Выплата отправлена
    description: >
      Совет авторизовал выплату, контракт инициировал исходящий платёж
      в Gateway, ожидается подтверждение списания.
    kind: normal
  - name: completed
    human: Возврат выплачен
    description: >
      Gateway подтвердил списание, сумма из резерва сжигается
      (BURN w.wal.wpend). В бухгалтерии прошла обратная
      проводка Дт 80 / Кт 51. Запись заявки удалена.
    kind: final
  - name: removed
    human: Отклонено
    description: >
      Возврат не состоялся: сумма возвращена из резерва на кошелёк пайщика
      (o.wal.wthdec: WITHDRAW_PENDING → SHARE_FUND_PAY), запись удалена.
    kind: virtual
    virtual: true

transitions:
  - from: "∅"
    to: pending
    action: wallet::createwthd
    actor: contributor
    ledger_code: o.wal.wthreq
    operations:
      - o.wal.wthreq
    guards:
      - Пайщик имеет статус active.
      - Сумма возврата ≤ доступного остатка на SHARE_FUND_PAY (w.wal.share).
      - withdraw_hash уникален.
      - Заявление подписано ЭЦП пайщика.

  - from: pending
    to: authorized
    action: wallet::authwthd
    actor: soviet
    guards:
      - Решение совета по повестке возврата подписано и авторизовано.

  - from: authorized
    to: completed
    action: wallet::completewthd
    actor: gateway_operator
    ledger_code: o.wal.wthcpl
    operations:
      - o.wal.wthcpl
    guards:
      - Gateway подтвердил списание средств в пользу пайщика.

  - from: pending
    to: removed
    action: wallet::declinewthd
    actor: soviet
    ledger_code: o.wal.wthdec
    operations:
      - o.wal.wthdec
    guards:
      - Совет отклонил возврат.

  - from: authorized
    to: removed
    action: wallet::declinewthd
    actor: gateway_operator
    ledger_code: o.wal.wthdec
    operations:
      - o.wal.wthdec
    guards:
      - Платёж не прошёл / отклонён Gateway.

# ── Секция 4. Сценарий ──────────────────────────────────────────────────────
scenario:
  steps:
    - step: 1
      title: Подача заявления о возврате
      actor: contributor
      action: wallet::createwthd
      description: >
        Пайщик оформляет и подписывает заявление о возврате паевого взноса.
        Контракт создаёт запись в таблице withdraws со статусом `pending`,
        блокирует сумму на кошельке SHARE_FUND_PAY и направляет в совет
        повестку о возврате с callback'ом авторизации.
      pre:
        - Пайщик — активный участник кооператива.
        - Сумма возврата ≤ доступного остатка.
      post:
        - В таблице withdraws создана запись со статусом `pending`.
        - Сумма переведена с SHARE_FUND_PAY в кошелёк-резерв WITHDRAW_PENDING.
        - Совет получил повестку о возврате.

    - step: 2
      title: Авторизация выплаты советом
      actor: soviet
      action: wallet::authwthd
      description: >
        Совет принимает положительное решение по повестке возврата и
        авторизует выплату единым шагом. Контракт инициирует исходящий
        платёж в Gateway с callback'ами completewthd / declinewthd.
        Статус заявки → `authorized`.
      pre:
        - Заявка в статусе `pending`.
        - Решение совета подписано и авторизовано председателем.
      post:
        - Статус заявки `authorized`.
        - В Gateway создан исходящий платёж с callback'ами.

    - step: 3
      title: Подтверждение выплаты
      actor: gateway_operator
      action: wallet::completewthd
      description: >
        Gateway подтверждает списание средств в пользу пайщика. Контракт
        применяет ledger2-операцию o.wal.wthcpl (BURN w.wal.wpend с
        обратной проводкой Дт 80 / Кт 51) и удаляет запись заявки.
      pre:
        - Заявка в статусе `authorized`.
        - Gateway подтвердил списание.
      post:
        - Сумма из резерва сожжена (WITHDRAW_PENDING, w.wal.wpend).
        - В ledger2 применена операция o.wal.wthcpl.
        - Запись заявки удалена.

  alternatives:
    - branch: Отказ совета или Gateway
      at_step: 2
      action: wallet::declinewthd
      actor: soviet
      description: >
        Совет принял отрицательное решение либо Gateway отклонил платёж.
        Сумма возвращена из резерва на кошелёк пайщика (o.wal.wthdec:
        WITHDRAW_PENDING → SHARE_FUND_PAY), запись удалена.

# ── Секция 5. Документы и подписи ───────────────────────────────────────────
documents:
  - step: 1
    title: Заявление на возврат паевого взноса денежными средствами
    registry_id: 900
    signed_by: [contributor]
    stored_in: withdraws.statement

  - step: 2
    title: Решение совета о возврате паевого взноса (авторизация на выплату)
    registry_id: 901
    signed_by: [soviet]
    stored_in: "(authorization — параметр действия)"

# ── Секция 6. Операции ──────────────────────────────────────────────────────
operations:
  - ledger_code: o.wal.wthreq
    human_name: Резервирование паевого под запрос на возврат
    wallet_op: TRANSFER
    wallet_from: w.wal.share
    wallet_to: w.wal.wpend
    debit: ~
    credit: ~
    amount_ref: withdraw.quantity
    triggered_by: wallet::createwthd
    description: >
      На создании заявки контракт переводит сумму с кошелька пайщика
      (SHARE_FUND_PAY) в кошелёк-резерв (WITHDRAW_PENDING). Бухгалтерская
      проводка не создаётся — движение внутри одного бухсчёта 80.

  - ledger_code: o.wal.wthdec
    human_name: Снятие резерва паевого после отклонения запроса на возврат
    wallet_op: TRANSFER
    wallet_from: w.wal.wpend
    wallet_to: w.wal.share
    debit: ~
    credit: ~
    amount_ref: withdraw.quantity
    triggered_by: wallet::declinewthd
    description: >
      Зеркало REQUEST_WITHDRAW: сумма возвращается из резерва (WITHDRAW_PENDING)
      на кошелёк пайщика (SHARE_FUND_PAY). Бухгалтерская проводка не создаётся.

  - ledger_code: o.wal.wthcpl
    human_name: Возврат паевого взноса пайщику
    wallet_op: BURN
    wallet_from: w.wal.wpend           # кошелёк-резерв возвратов
    wallet_to: ~                       # деньги уходят из системы, получателя на цепи нет
    debit: 80                  # Паевой фонд (складочный капитал)
    credit: 51                 # Расчётный счёт
    amount_ref: withdraw.quantity
    triggered_by: wallet::completewthd
    description: >
      Обратная операция к o.wal.depcpl: зарезервированная сумма сжигается с
      кошелька-резерва (w.wal.wpend) — деньги уходят из системы банковским
      переводом пайщику. На цепи получателя нет.
      В бухгалтерии прошла проводка Дт 80 / Кт 51 — паевой фонд уменьшился,
      деньги ушли с расчётного счёта пайщику.

# ── Секция 7. Связи ─────────────────────────────────────────────────────────
related:
  - process_type: p.wal.depo
    id: public_wallet_deposit_process
    relation: affects
    note: >
      Прямой процесс — внесение паевого взноса (p.wal.depo). Возврат
      списывается с того же кошелька SHARE_FUND_PAY, который пополняется
      депозитом.

  - process_type: p.reg.accept
    id: public_registrator_accept_process
    relation: provides
    note: >
      Возврат возможен только если пайщик прошёл «Приём пайщика» и имеет
      статус active с положительным остатком на SHARE_FUND_PAY.
