mono/components/contracts/cpp/lib/MASTER_APPROVALS_IMPLEMENTATION.md

Реализация системы аппрувов мастера проекта

Обзор

Реализована переиспользуемая система одобрений (аппрувов) для контракта Capital, которая позволяет мастеру проекта одобрять или отклонять коммиты через единообразный интерфейс.

Архитектурные изменения

1. Переиспользуемая базовая структура (lib/shared_approver.hpp)

Создана базовая структура approval_base, которая не привязана к конкретному контракту и может быть переиспользована:

struct approval_base {
  uint64_t         id;
  eosio::name      coopname;
  eosio::name      username;
  eosio::name      type;
  document2        document;
  checksum256      approval_hash;
  eosio::name      callback_contract;
  eosio::name      callback_action_approve;
  eosio::name      callback_action_decline;
  std::string      meta;
  eosio::time_point_sec created_at;
  // ... индексы
};

Добавлены макросы для создания специализированных версий:

• DEFINE_APPROVAL_STRUCT(name, contract) - создает структуру для конкретного контракта
• DEFINE_APPROVALS_INDEX(index_name, struct_name) - создает мультииндекс

2. Библиотека для Capital (lib/shared_capital.hpp)

Создан новый файл с:

• Сигнатурами действий для аппрувов мастера
• Namespace Master с таблицей аппрувов для контракта Capital
• Функцией Master::create_approval() для создания аппрувов

3. Действия в контракте Capital

Добавлены три новых действия в capital.hpp:

createapprv - Создание аппрува

• Авторизация: _capital
• Создает запись в таблице аппрувов мастера
• Используется внутренне при создании коммита

confirmapprv - Подтверждение аппрува

• Авторизация: coopname
• Находит аппрув по хешу
• Вызывает колбэк одобрения
• Удаляет аппрув из таблицы

declineapprv - Отклонение аппрува

• Авторизация: coopname
• Находит аппрув по хешу
• Вызывает колбэк отклонения
• Удаляет аппрув из таблицы

4. Интеграция с процессом создания коммитов

Изменения в createcmmt

Теперь при создании коммита:

1. Создается запись коммита в таблице
2. Создается аппрув через Master::create_approval() с:
   • type = "commit"
   • approval_hash = commit_hash
   • callback_action_approve = "approvecmmt"
   • callback_action_decline = "declinecmmt"

Изменения в approvecmmt

Теперь работает как колбэк:

• Авторизация: _capital (вместо coopname)
• Сигнатура: (coopname, commit_hash, approved_document)
• Вызывается автоматически из confirmapprv
• Убрана проверка мастера (она выполняется на уровне фронтенда)

Изменения в declinecmmt

Теперь работает как колбэк:

• Авторизация: _capital (вместо coopname)
• Сигнатура: (coopname, commit_hash, reason)
• Вызывается автоматически из declineapprv
• Убрана проверка мастера (она выполняется на уровне фронтенда)

Структура файлов

contracts/cpp/
├── lib/
│   ├── shared_approver.hpp      # Переиспользуемая базовая структура
│   ├── shared_capital.hpp       # NEW: Методы для аппрувов мастера
│   └── common.hpp               # Обновлен: добавлен include shared_capital.hpp
└── capital/
    ├── capital.hpp              # Обновлен: добавлены действия createapprv/confirmapprv/declineapprv
    ├── capital.cpp              # Обновлен: добавлены includes для master_approval
    └── app/
        ├── master_approval/     # NEW: Директория с аппрувами мастера
        │   ├── createapprv.cpp
        │   ├── confirmapprv.cpp
        │   ├── declineapprv.cpp
        │   └── master-approval-process.dox  # Документация процесса
        └── generation/
            └── create_commit/
                ├── createcmmt.cpp          # Обновлен: добавлено создание аппрува
                ├── approvecmmt.cpp         # Обновлен: теперь колбэк
                ├── declinecmmt.cpp         # Обновлен: теперь колбэк
                └── commit-creation-process.dox  # Обновлена документация

Процесс работы

Создание коммита

Исполнитель → createcmmt → Создание коммита → Master::create_approval() → Аппрув в таблице

Одобрение коммита

Мастер → confirmapprv → Поиск аппрува → Колбэк approvecmmt → Обработка коммита → Удаление аппрува

Отклонение коммита

Мастер → declineapprv → Поиск аппрува → Колбэк declinecmmt → Удаление коммита → Удаление аппрува

Преимущества реализации

1. Переиспользуемость: Базовая структура approval_base может быть использована в любых других контрактах
2. Единообразие: Аппрувы председателя и мастера используют одинаковую структуру и логику
3. Разделение ответственности: Таблицы аппрувов разделены (soviet и capital), данные не перемешиваются
4. Гибкость: Легко добавить новые типы аппрувов в будущем
5. Колбэки: Унифицированный механизм обратных вызовов при одобрении/отклонении

Дальнейшее использование

Для создания аналогичной системы в других контрактах:

1. Определить сигнатуры действий в lib/shared_<contract>.hpp
2. Использовать макросы DEFINE_APPROVAL_STRUCT и DEFINE_APPROVALS_INDEX
3. Реализовать действия createapprv, confirmapprv, declineapprv
4. Создать функцию create_approval() в namespace контракта
5. Интегрировать с бизнес-процессами через колбэки

Миграция данных

Не требуется - это новая функциональность, существующие данные не затронуты.

Тестирование

Рекомендуется протестировать:

1. Создание коммита и аппрува
2. Одобрение коммита мастером
3. Отклонение коммита мастером
4. Проверку прав доступа (только кооператив может подтверждать/отклонять)
5. Корректность колбэков
6. Удаление аппрувов после обработки