mono/MARKET-LOGIC.md

MARKET-LOGIC.md — Бизнес-процессы маркетплейса

2А. БИЗНЕС-ПРОЦЕССЫ СМАРТ-КОНТРАКТОВ

Основные бизнес-сценарии

Сценарий 1: Поставка-приобретение имущества

• Описание: Обмен имущества между пайщиками через кооператив с блокировкой средств и документооборотом
• Участники: Заказчик, Поставщик, Совет кооператива, Председатель КУ
• Бизнес-ценность: Основной процесс кооперативного маркетплейса

Сценарий 1А. Прямая поставка (OFFER→ORDER) — поставщик публикует, заказчик откликается Сценарий 1Б. Обратная поставка (ORDER→OFFER) — заказчик публикует, поставщики откликаются Сценарий 1В. Из запасов кооператива (COOPSTOCK) — имущество уже на балансе

Сценарий 2: Гарантийный возврат

• Описание: Возврат бракованного имущества в течение гарантийного срока
• Участники: Заказчик, Поставщик, Председатель КУ, Совет
• Бизнес-ценность: Защита интересов пайщика и качества имущества

Сценарий 3: Уничтожение/перепредложение

• Описание: Утилизация просроченного или перепродажа по новой цене
• Участники: Председатель КУ, Совет
• Бизнес-ценность: Управление складскими запасами и минимизация потерь

Сценарий 4: Транспортировка

• Описание: Перевозка имущества между КУ группами
• Участники: Председатель КУ отправителя, Водитель, Председатель КУ получателя
• Бизнес-ценность: Логистика распределённой кооперативной сети

---

Процесс 1А: Прямая поставка (OFFER→ORDER)

Предусловия:

• Поставщик создал карточку товара в БД (статус: published)
• Заказчик нашёл карточку на витрине и решил заказать
• У заказчика достаточно средств на цифровом кошельке

Последовательность шагов:

Шаг 1: orderoffer — Заказчик создаёт заявку

• Предусловие: Карточка товара в БД (published). При создании заявки происходит match — заявка публикуется в блокчейн
• Исполнитель: Заказчик (через контроллер, авторизация от кооператива)
• Подписываемые документы: Заявление на конвертацию из кошелька (convert_in)
• Проводки по кошелькам:
  • Списать у заказчика total_cost из ЦПП «Цифровой Кошелёк»
  • Начислить заказчику total_cost в ЦПП «Маркетплейс»
  • Заблокировать у заказчика total_cost в ЦПП «Маркетплейс»
• Статус заявки: active
• Параметры: delivery_type (internal/external), contribution_type (share/member)

Шаг 2: accept — Поставщик принимает заявку

• Исполнитель: Поставщик
• Подписываемые документы:
  • Заявление на конвертацию в кошелёк (convert_out)
  • Заявление на имущественный паевой взнос (contribution_statement)
• Проводки: Нет
• Эффект: Создаётся одно заявление в совет — authcontrib (авторизация взноса)
• Статус заявки: accepted

Шаг 3: authcontrib — Совет авторизует взнос

• Исполнитель: Совет кооператива (автоматически через soviet контракт)
• Подписываемые документы: Решение совета об авторизации взноса
• Проводки: Нет
• Статус заявки: authorized — поставщик может начинать поставку

Шаг 4: supply — Поставщик поставляет имущество на КУ

• Исполнитель: Поставщик
• Подписываемые документы: Акт поставки (supply_act)
• Проводки: Нет
• Статус заявки: supplied1

Шаг 5: supplcnf — Председатель КУ подтверждает поставку

• Исполнитель: Председатель КУ поставщика
• Подписываемые документы: Акт подтверждения поставки (supply_act_conf)
• Проводки по кошелькам:
  • Начислить поставщику base_cost в ЦПП «Маркетплейс»
  • Заблокировать у поставщика base_cost в ЦПП «Маркетплейс»
• Проводки по ledger:
  • Увеличить паевой фонд (счёт 80) на total_cost
• Статус заявки: supplied2, имущество на складе КУ

Шаг 6: [Транспортировка] — При необходимости (см. Сценарий 4)

Шаг 7: delivered — Готово к выдаче

• Исполнитель: Председатель КУ получателя
• Подписываемые документы: Нет
• Проводки: Нет
• Статус заявки: delivered

Шаг 8: reqreturn — Заказчик запрашивает возврат

• Исполнитель: Заказчик
• Подписываемые документы: Заявление на возврат паевого взноса имуществом (return_statement) — с актуальными данными о весе/составе
• Проводки: Нет
• Эффект: Создаётся заявление в совет — authreturn
• Статус заявки: reqreturn

Шаг 9: authreturn — Совет авторизует возврат

• Исполнитель: Совет кооператива
• Подписываемые документы: Решение совета об авторизации возврата
• Проводки: Нет
• Статус заявки: retauthorized

Шаг 10: receive — Председатель КУ передаёт имущество

• Исполнитель: Председатель КУ
• Подписываемые документы: Акт приёма-передачи (receive_act)
• Проводки: Нет
• Статус заявки: received1

Шаг 11: receivecnf — Заказчик подтверждает получение

• Исполнитель: Заказчик
• Подписываемые документы: Акт подтверждения получения (receive_act_conf)
• Проводки по кошелькам:
  • Списать заблокированный баланс заказчика total_cost из ЦПП «Маркетплейс»
• Проводки по ledger:
  • Уменьшить паевой фонд (счёт 80) на base_cost
• Статус заявки: received2
• Эффект: Устанавливается warranty_delay_until (текущее время + гарантийный срок)

Шаг 12: complete — Завершение после гарантии

• Исполнитель: Система (после истечения warranty_delay_until)
• Проводки по кошелькам:
  • Списать заблокированный баланс поставщика base_cost из ЦПП «Маркетплейс»
  • Начислить поставщику base_cost в ЦПП «Цифровой Кошелёк»
• Статус: Заявка удаляется из блокчейна

Постусловия:

• Заказчик получил имущество
• Поставщик получил средства на кошелёк
• Членские взносы распределены по фондам кооператива

---

Процесс 1Б: Обратная поставка (ORDER→OFFER)

Предусловия:

• Заказчик создал карточку заказа в БД (статус: published, тип: order)
• Поставщик нашёл заказ и готов поставить

Последовательность шагов:

Шаг 1: createorder — Заказчик публикует заказ

• Предусловие: Карточка заказа в БД. При публикации — match в блокчейн
• Проводки: Списание + блокировка total_cost заказчика (аналогично orderoffer)
• Статус: active

Шаг 2: respondoffer — Поставщик откликается

• Исполнитель: Поставщик
• Подписываемые документы: Заявление на взнос + конвертация
• Эффект: Создаётся заявление в совет authcontrib
• Статус предложения: accepted

Шаги 3-12: Аналогичны Процессу 1А (authcontrib → complete)

---

Процесс 1В: Из запасов кооператива (COOPSTOCK)

Предусловия:

• Имущество уже на балансе кооператива (на складе КУ)
• Председатель КУ создаёт предложение coopstock

Последовательность шагов:

Шаг 1: coopstock — Создание предложения

• Исполнитель: Председатель КУ
• Проводки: Нет (имущество уже на балансе)
• Статус: delivered (сразу готово к выдаче)

Шаг 2: acceptstock — Заказчик принимает

• Исполнитель: Заказчик
• Подписываемые документы: Конвертация + заявление на возврат
• Проводки: Блокировка total_cost заказчика
• Эффект: Сразу создаётся заявление в совет authreturn
• Статус: reqreturn

Шаги 3-6: authreturn → receive → receivecnf → complete (аналогично 1А шаги 9-12)

Особенности:

• Пропущены шаги accept, authcontrib, supply, supplcnf — не нужны
• Нет проводок по паевому фонду при поставке (имущество уже на балансе)

---

Процесс 2: Гарантийный возврат

Предусловия:

• Заявка в статусе received2 (имущество получено)
• Не истёк warranty_delay_until
• Заказчик обнаружил дефект

Последовательность шагов:

Шаг 1: dispute — Заказчик подаёт претензию

• Подписываемые документы: Претензия (wdispute) + фото/видео
• Эффект: Деньги поставщика дополнительно блокируются

Шаг 2: Рассмотрение на КУ (вне контракта)

• Исполнитель: Председатель КУ
• Действия: Осмотр, подтверждение/отклонение претензии

Шаг 3: wauthorize — Совет авторизует возврат

• Подписываемые документы: Решение о возврате (wreturn_auth) + решение о выдаче поставщику (wsupply_auth)

Шаг 4: wreturn — Возврат имущества в кооператив

• Проводки: Разблокировка средств заказчика, начисление на кошелёк

Шаг 5: woffer — Предложение имущества поставщику

Шаг 6: waccept — Поставщик принимает/отказывается

Альтернативные потоки:

• Отклонение претензии: Заказчик забирает имущество обратно
• Поставщик не забрал: Имущество перепредлагается (→ reoffer) или уничтожается (→ destroy)

---

Процесс 3: Уничтожение имущества

Предусловия:

• Заявка в статусе delivered или supplied2
• Истёк deadline_for_receipt (заказчик не пришёл)

Шаг 1: destroy — Уничтожение

• Исполнитель: Председатель КУ (chairman)
• Подписываемые документы: Акт уничтожения (destruction_act)
• Проводки:
  • Возврат заказчику: total_cost - cancellation_fee → разблокировать и вернуть в кошелёк
  • Штраф cancellation_fee → в фонд членских взносов (spreadamount)
  • Поставщику: base_cost → разблокировать и вернуть в кошелёк
• Эффект: Заявка удаляется из блокчейна

---

Процесс 3Б: Перепредложение (reoffer)

Предусловия:

• Аналогичны destroy, но срок годности НЕ истёк

Шаг 1: reoffer — Перепредложение по новой цене

• Исполнитель: Председатель КУ
• Проводки: Аналогичны destroy (возврат средств)
• Эффект: Старая заявка удаляется, создаётся новая типа coopstock со статусом delivered

---

Процесс 4: Транспортировка (Shipment)

Предусловия:

• Имущество на складе КУ (статус supplied2 или shiprecvd)
• Нужно доставить на другой КУ

Последовательность шагов:

Шаг 1: createship — Создание перевозки

• Исполнитель: Представитель КУ отправителя
• Документ: Акт передачи (shsendact)
• Статус перевозки: loading

Шаг 2: signbydriver — Подпись водителя

• Исполнитель: Водитель-пайщик
• Документ: Акт приёма (shloadact)
• Эффект: Товары снимаются со склада
• Статус: transit

Шаг 3: arrived — Прибытие

• Исполнитель: Водитель
• Документ: Акт доставки (sharriveact)
• Статус: arrived

Шаг 4: receiveshipm — Приём на складе

• Исполнитель: Представитель КУ получателя
• Документ: Акт приёма на складе (shrecvact)
• Эффект: Товары ставятся на склад КУ назначения, перевозка удаляется
• Статус заявок: shiprecvd

Альтернативный поток: retransport — промежуточная перегрузка на другой маршрут

---

Связи между процессами

• Процесс 1 → Процесс 4: После supplcnf (шаг 5) товар может пойти на транспортировку перед delivered
• Процесс 1 → Процесс 2: После receivecnf (шаг 11) возможен гарантийный возврат до истечения warranty_delay_until
• Процесс 2 → Процесс 3: Если поставщик не забирает возвращённое имущество → destroy/reoffer
• Процесс 1 → Процесс 3: Если заказчик не приходит за товаром → destroy/reoffer
• Процесс 3Б → Процесс 1В: reoffer создаёт coopstock → новый цикл 1В

Бизнес-правила и ограничения

Правило 1: Блокировка средств при заказе

• Описание: Средства заказчика блокируются в момент создания заявки в блокчейне (match)
• Применение: orderoffer, createorder, acceptstock
• Последствия нарушения: Заявка не может быть создана без достаточных средств

Правило 2: Одно заявление в совет при принятии

• Описание: При accept создаётся только authcontrib (на взнос). authreturn — перед получением
• Применение: accept, reqreturn
• Обоснование: Заявление на возврат содержит точные данные (вес), доступные после доставки

Правило 3: Тип доставки определяет маршрут

• Описание: delivery_type: internal — между КУ через Shipment, external — через внешний сервис (СДЭК)
• Применение: Определяется в карточке при создании

Правило 4: Тип взноса определяет проводки

• Описание: contribution_type: share — паевой взнос (возврат имуществом), member — членский взнос (кооператив покупает)
• Применение: Влияет на проводки при complete

Правило 5: Гарантийный период

• Описание: warranty_delay_until = received_at + warranty_period_secs. До истечения — complete невозможен, dispute возможен
• Применение: complete, dispute

Правило 6: Карточки в БД до match

• Описание: Карточки хранятся в PostgreSQL (draft → moderation → published). В блокчейн уходят только при match
• Применение: Все процессы создания заявок