DLE/docs/DLE_Governance_System.md

<!--
  Copyright (c) 2024-2025 Тарабанов Александр Викторович
  All rights reserved.
  
  This software is proprietary and confidential.
  Unauthorized copying, modification, or distribution is prohibited.
  
  For licensing inquiries: info@hb3-accelerator.com
  Website: https://hb3-accelerator.com
  GitHub: https://github.com/HB3-ACCELERATOR
-->

# DLE Governance System - Документация

## 📋 Обзор системы

DLE (Digital Legal Entity) - это система управления цифровым юридическим лицом с использованием смарт-контрактов и токенов управления. Система включает в себя механизмы голосования, мультиподписи и административного управления.

## 🏗️ Архитектура системы

### Текущие смарт-контракты

#### 1. GovernanceToken.sol
```solidity
contract GovernanceToken is ERC20Permit, ERC20Votes, Ownable {
    // Основные функции:
    - mintInitialSupply(address[] partners, uint256[] amounts) // Начальное распределение токенов
    - transfer() // Передача токенов
    - balanceOf() // Проверка баланса
    - getVotes() // Получение голосов на определенном блоке
}
```

#### 2. GovernanceTimelock.sol
```solidity
contract GovernanceTimelock is TimelockController {
    // Основные функции:
    - queue() // Постановка операции в очередь
    - execute() // Выполнение операции после задержки
    - cancel() // Отмена операции
}
```

#### 3. GovernorContract.sol
```solidity
contract GovernorContract is Governor, GovernorSettings, GovernorCountingSimple, GovernorVotes, GovernorVotesQuorumFraction, GovernorTimelockControl {
    // Основные функции:
    - propose() // Создание предложения
    - vote() // Голосование
    - execute() // Выполнение предложения
    - cancel() // Отмена предложения
}
```

### Текущие параметры системы
- **Порог предложения**: 100,000 GT
- **Кворум**: 4% от общего количества токенов
- **Задержка голосования**: 1 день
- **Период голосования**: 7 дней
- **Минимальная задержка Timelock**: 2 дня

## 🔧 Функции приложения

### Критические функции (требуют голосования)

#### 🚨 УДАЛЕНИЕ ДАННЫХ

##### Пользователи
```javascript
// Удаление пользователя
DELETE /api/users/:id
- Описание: Полное удаление пользователя и всех связанных данных
- Критичность: 🔴 ВЫСОКАЯ
- Требует голосования: ДА

// Блокировка пользователя
PATCH /api/users/:id/block
- Описание: Блокировка пользователя в системе
- Критичность: 🔴 ВЫСОКАЯ
- Требует голосования: ДА
```

##### Таблицы
```javascript
// Удаление таблицы
DELETE /api/tables/:id
- Описание: Удаление таблицы и всех связанных данных
- Критичность: 🔴 ВЫСОКАЯ
- Требует голосования: ДА

// Удаление строк таблицы
DELETE /api/tables/:id/rows
- Описание: Массовое удаление строк
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ДА

// Удаление столбцов таблицы
DELETE /api/tables/:id/columns
- Описание: Удаление столбцов таблицы
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ДА
```

##### DLE (Digital Legal Entity)
```javascript
// Удаление DLE
DELETE /api/dle/:tokenAddress
- Описание: Удаление DLE по адресу токена
- Критичность: 🔴 ВЫСОКАЯ
- Требует голосования: ДА

// Удаление пустого DLE
DELETE /api/dle/empty/:fileName
- Описание: Удаление пустого DLE по имени файла
- Критичность: 🔴 ВЫСОКАЯ
- Требует голосования: ДА
```

##### Системные настройки
```javascript
// Удаление RPC провайдера
DELETE /api/settings/rpc/:networkId
- Описание: Удаление RPC конфигурации
- Критичность: 🔴 ВЫСОКАЯ
- Требует голосования: ДА

// Удаление токена аутентификации
DELETE /api/settings/auth-token/:address/:network
- Описание: Удаление токена для аутентификации
- Критичность: 🔴 ВЫСОКАЯ
- Требует голосования: ДА

// Удаление AI настроек
DELETE /api/settings/ai-settings/:provider
- Описание: Удаление настроек AI провайдера
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ДА

// Удаление правил AI ассистента
DELETE /api/settings/ai-assistant-rules/:id
- Описание: Удаление набора правил AI
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ДА
```

#### 🏗️ СОЗДАНИЕ КРИТИЧНЫХ СУЩНОСТЕЙ

##### DLE
```javascript
// Создание нового DLE
POST /api/dle
- Описание: Создание нового Digital Legal Entity
- Критичность: 🔴 ВЫСОКАЯ
- Требует голосования: ДА
- Параметры: name, symbol, location, isicCodes, partners, amounts, network, etc.
```

##### Таблицы
```javascript
// Создание таблицы
POST /api/tables
- Описание: Создание новой таблицы
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ДА
```

##### Системные настройки
```javascript
// Добавление RPC провайдера
POST /api/settings/rpc
- Описание: Добавление нового RPC провайдера
- Критичность: 🔴 ВЫСОКАЯ
- Требует голосования: ДА

// Добавление токена аутентификации
POST /api/settings/auth-token
- Описание: Добавление нового токена для аутентификации
- Критичность: 🔴 ВЫСОКАЯ
- Требует голосования: ДА
```

#### ⚙️ ИЗМЕНЕНИЕ СИСТЕМНЫХ НАСТРОЕК

##### База данных
```javascript
// Изменение настроек БД
PUT /api/settings/db-settings
- Описание: Изменение параметров подключения к базе данных
- Критичность: 🔴 ВЫСОКАЯ
- Требует голосования: ДА
- Параметры: db_host, db_port, db_name, db_user, db_password
```

##### AI настройки
```javascript
// Изменение настроек AI ассистента
PUT /api/settings/ai-assistant
- Описание: Изменение глобальных настроек AI ассистента
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ДА

// Изменение AI провайдера
PUT /api/settings/ai-settings/:provider
- Описание: Изменение настроек конкретного AI провайдера
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ДА
```

##### Коммуникации
```javascript
// Настройки Email
PUT /api/identities/email-settings
- Описание: Изменение настроек SMTP/IMAP
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ДА

// Настройки Telegram
PUT /api/identities/telegram-settings
- Описание: Изменение настроек Telegram бота
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ДА
```

### Умеренные функции (опциональное голосование)

#### 📝 РЕДАКТИРОВАНИЕ ДАННЫХ

```javascript
// Редактирование пользователя
PATCH /api/users/:id
- Описание: Изменение данных пользователя
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ОПЦИОНАЛЬНО

// Редактирование таблицы
PATCH /api/tables/:id
- Описание: Изменение структуры таблицы
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ОПЦИОНАЛЬНО

// Импорт пользователей
POST /api/users/import
- Описание: Массовый импорт пользователей
- Критичность: 🟡 СРЕДНЯЯ
- Требует голосования: ОПЦИОНАЛЬНО
```

### Обычные функции (не требуют голосования)

#### 📖 ПРОСМОТР ДАННЫХ

```javascript
// Список пользователей
GET /api/users
- Описание: Получение списка пользователей
- Критичность: 🟢 НИЗКАЯ
- Требует голосования: НЕТ

// Список таблиц
GET /api/tables
- Описание: Получение списка таблиц
- Критичность: 🟢 НИЗКАЯ
- Требует голосования: НЕТ

// Список DLE
GET /api/dle
- Описание: Получение списка DLE
- Критичность: 🟢 НИЗКАЯ
- Требует голосования: НЕТ

// Детали пользователя
GET /api/users/:id
- Описание: Получение детальной информации о пользователе
- Критичность: 🟢 НИЗКАЯ
- Требует голосования: НЕТ
```

#### ✏️ РЕДАКТИРОВАНИЕ ЯЧЕЕК

```javascript
// Изменение значения ячейки
PATCH /api/tables/cell
- Описание: Изменение значения конкретной ячейки таблицы
- Критичность: 🟢 НИЗКАЯ
- Требует голосования: НЕТ
```

## 🎯 Система голосования

### Текущая реализация

#### Процесс голосования
1. **Создание предложения** - пользователь с достаточным количеством токенов создает предложение
2. **Период голосования** - 7 дней для голосования
3. **Подсчет голосов** - проверка кворума (4% от общего количества токенов)
4. **Постановка в очередь** - успешные предложения ставятся в очередь Timelock
5. **Выполнение** - после задержки (2 дня) предложение выполняется

#### Параметры голосования
- **Порог для создания предложений**: 100,000 GT
- **Кворум**: 4% от общего количества токенов
- **Задержка голосования**: 1 день (в блоках)
- **Период голосования**: 7 дней (в блоках)
- **Минимальная задержка Timelock**: 2 дня

### Предлагаемые улучшения

#### Новый модуль: AdminGovernanceModule

```solidity
contract AdminGovernanceModule {
    struct AdminAction {
        string actionType;     // Тип действия
        string targetId;       // ID цели
        bytes actionData;      // Данные действия
        uint256 proposalId;    // ID предложения
        bool executed;         // Выполнено ли
        uint256 createdAt;     // Время создания
    }
    
    mapping(uint256 => AdminAction) public adminActions;
    mapping(string => bool) public actionTypesRequiringVote;
    
    // Функции
    function proposeAdminAction(string memory actionType, string memory targetId, bytes memory actionData) external returns (uint256);
    function executeAdminAction(uint256 actionId) external;
    function canExecuteAction(address executor, string memory actionType) external view returns (bool);
}
```

#### Типы административных действий

```solidity
// Критические действия (обязательное голосование)
"DELETE_USER"           // Удаление пользователя
"DELETE_DLE"           // Удаление DLE
"DELETE_TABLE"         // Удаление таблицы
"CREATE_DLE"           // Создание DLE
"UPDATE_DB_SETTINGS"   // Изменение настроек БД
"UPDATE_RPC"           // Изменение RPC настроек
"UPDATE_AUTH_TOKENS"   // Изменение токенов аутентификации

// Важные действия (опциональное голосование)
"CREATE_TABLE"         // Создание таблицы
"UPDATE_AI_SETTINGS"   // Изменение AI настроек
"UPDATE_EMAIL_SETTINGS" // Изменение email настроек
"UPDATE_TELEGRAM_SETTINGS" // Изменение telegram настроек
"IMPORT_USERS"         // Импорт пользователей
```

## 🔐 Система доступа

### Текущая система ролей

#### Роли пользователей
- **Администратор** - полный доступ ко всем функциям
- **Пользователь** - ограниченный доступ

#### Проверка прав
```javascript
// Middleware для проверки администратора
requireAdmin(req, res, next) {
    // Проверка через сессию
    if (req.session.isAdmin) return next();
    
    // Проверка через кошелек
    if (req.session.address) {
        const isAdmin = await authService.checkAdminTokens(req.session.address);
        if (isAdmin) return next();
    }
    
    // Проверка через ID пользователя
    if (req.session.userId) {
        const user = await db.getQuery()('SELECT role FROM users WHERE id = $1', [req.session.userId]);
        if (user.rows[0].role === 'admin') return next();
    }
    
    return res.status(403).json({ error: 'Доступ запрещен' });
}
```

### Предлагаемая система доступа с токенами

#### Проверка через смарт-контракт
```solidity
function canExecuteAction(address executor, string memory actionType) public view returns (bool) {
    // Проверка баланса токенов
    uint256 balance = governanceToken.balanceOf(executor);
    
    // Проверка типа действия
    if (actionTypesRequiringVote[actionType]) {
        return balance >= proposalThreshold;
    }
    
    // Для некритических действий достаточно быть администратором
    return adminService.isAdmin(executor);
}
```

## 📊 Модули DLE

### Текущие модули

#### Доступные модули
1. **Контракт на активы** - токенизация физических активов
2. **Мультиподпись** - повышенная безопасность
3. **Дивиденды** - распределение дивидендов между держателями
4. **Стейкинг** - стейкинг токенов для получения наград
5. **Прием платежей** - прием оплаты в выбранных токенах

#### Предлагаемый модуль: Административное голосование
```javascript
{
    name: 'Административное голосование',
    description: 'Добавляет систему голосования для административных действий',
    installed: false,
    features: [
        'Голосование за удаление пользователей',
        'Голосование за создание таблиц',
        'Голосование за изменение системных настроек',
        'Интеграция с существующими контрактами DLE'
    ]
}
```

## 🚀 План реализации

### Этап 1: Анализ и проектирование
- [x] Анализ текущих функций приложения
- [x] Определение критических операций
- [x] Проектирование архитектуры системы голосования

### Этап 2: Разработка смарт-контрактов
- [ ] Создание AdminGovernanceModule
- [ ] Расширение GovernorContract
- [ ] Создание интерфейсов для взаимодействия

### Этап 3: Интеграция с приложением
- [ ] Создание сервиса для работы с голосованием
- [ ] Интеграция с существующими API
- [ ] Обновление middleware для проверки прав

### Этап 4: Обновление UI
- [ ] Создание интерфейса для управления предложениями
- [ ] Интеграция с модульной системой DLE
- [ ] Добавление уведомлений о голосованиях

### Этап 5: Тестирование и развертывание
- [ ] Тестирование смарт-контрактов
- [ ] Интеграционное тестирование
- [ ] Развертывание в production

## 📝 Заключение

Текущая система DLE предоставляет базовую функциональность управления через токены, но требует расширения для полной интеграции с административными функциями приложения. Предлагаемая система голосования позволит обеспечить безопасность и прозрачность при выполнении критических операций.

### Ключевые преимущества предлагаемого решения:
1. **Безопасность** - все критические операции требуют голосования
2. **Прозрачность** - все действия записываются в блокчейн
3. **Гибкость** - возможность настройки уровней критичности
4. **Интеграция** - использование существующей инфраструктуры DLE
5. **Модульность** - возможность включения/выключения функций

---

# 🏗️ Архитектура DLE как цифрового акционерного общества

## 🎯 Концепция DLE

DLE (Digital Legal Entity) - это **цифровое акционерное общество**, где смарт-контракт сам по себе является **цифровым ИНН организации** со всеми функциями традиционного АО.

### **Основная аналогия:**
```
Акционерное общество:
├── ИНН (идентификатор)
├── Банковский счет (финансы)
├── Юридический адрес
├── Контакты (телефон, email)
├── Коды деятельности (ОКВЭД)
├── Акционеры (владельцы)
├── Управление (голосование)
└── Участие в других организациях

DLE (цифровой аналог):
├── Адрес контракта (идентификатор)
├── Токены управления (акции)
├── Цифровой адрес (блокчейн)
├── Контакты (веб-интерфейс)
├── Коды деятельности (ISIC)
├── Держатели токенов (акционеры)
├── Система голосования
└── Участие в других DLE
```

## 📋 Формы для ручного деплоя смарт-контрактов

### **Основная форма деплоя DLE:**

#### **Блок 1: Идентификация (ИНН)**
```
- Название организации (name)
- Символ токена (symbol) 
- Описание деятельности (businessDescription)
- Юридический адрес (legalAddress)
- Контактная информация (contactInfo)
```

#### **Блок 2: Коды деятельности (ISIC)**
```
- Выбор секций ISIC (A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U)
- Выбор разделов (2-значные коды)
- Выбор групп (3-значные коды)
- Выбор классов (4-значные коды)
- Дополнительные коды деятельности
```

#### **Блок 3: Финансы (банковский счет)**
```
- Начальное распределение токенов (partners[], amounts[])
- Общее количество токенов (totalSupply)
- Минимальный баланс для голосования (proposalThreshold)
- Кворум для принятия решений (quorumPercentage)
```

#### **Блок 4: Управление (акционерное собрание)**
```
- Задержка голосования (votingDelay)
- Период голосования (votingPeriod)
- Минимальная задержка выполнения (timelockMinDelay)
- Тип управления (демократическое/олигархическое)
```

#### **Блок 5: Мультиподпись**
```
- Количество требуемых подписей (requiredSignatures)
- Список авторизованных подписантов (authorizedSigners[])
- Временные ограничения на подписание
- Типы операций, требующие мультиподпись
```

#### **Блок 6: Коммуникация**
```
- Веб-сайт организации (website)
- Email для связи (contactEmail)
- Телефон для связи (contactPhone)
- Адрес для сообщений (communicationAddress)
```

## 🏗️ Типы и функции смарт-контрактов

### **Основной контракт: DigitalLegalEntity.sol**

#### **A. Функции идентификации:**
```solidity
- getName() - получение названия
- getSymbol() - получение символа
- getContractAddress() - получение адреса (ИНН)
- getBusinessDescription() - получение описания
- getLegalAddress() - получение юр. адреса
- getContactInfo() - получение контактов
```

#### **B. Функции кодов деятельности:**
```solidity
- getIsicCodes() - получение кодов ISIC
- addIsicCode(string code) - добавление кода
- removeIsicCode(string code) - удаление кода
- updateBusinessDescription(string description) - обновление описания
```

#### **C. Финансовые функции:**
```solidity
- receive() - прием ETH
- receiveERC20(address token, uint256 amount) - прием токенов
- getBalance() - получение баланса
- distributePayment(address[] recipients, uint256[] amounts) - распределение
- mintTokens(address to, uint256 amount) - эмиссия токенов
- transferTokens(address to, uint256 amount) - передача токенов
- getTotalSupply() - общее количество токенов
```

#### **D. Функции управления:**
```solidity
- createProposal(string title, string description, ProposalType type) - создание предложения
- vote(uint256 proposalId, bool support) - голосование
- executeProposal(uint256 proposalId) - выполнение предложения
- cancelProposal(uint256 proposalId) - отмена предложения
- getProposalStatus(uint256 proposalId) - статус предложения
- getVotingPower(address account) - голосующая сила
```

#### **E. Функции участия в других DLE:**
```solidity
- participateInDLE(address dleAddress, uint256 tokens) - участие в другом DLE
- voteInOtherDLE(address dleAddress, uint256 proposalId, bool support) - голосование в другом DLE
- getParticipation(address dleAddress) - получение информации об участии
- withdrawFromDLE(address dleAddress, uint256 tokens) - выход из DLE
```

#### **F. Функции мультиподписи:**
```solidity
- requireMultiSignature(bytes32 operationId, uint256 requiredSignatures) - требование мультиподписи
- signOperation(bytes32 operationId) - подписание операции
- getSignatureCount(bytes32 operationId) - количество подписей
- addAuthorizedSigner(address signer) - добавление подписанта
- removeAuthorizedSigner(address signer) - удаление подписанта
```

#### **G. Коммуникационные функции:**
```solidity
- sendMessage(string message, string senderInfo) - отправка сообщения
- respondToMessage(uint256 messageId, string response) - ответ на сообщение
- initiateCall(string callerInfo, string purpose) - запрос звонка
- acceptCall(uint256 callId, string response) - принятие звонка
- rejectCall(uint256 callId, string reason) - отклонение звонка
```

## 🧩 Модули для настройки смарт-контракта

### **Базовые модули:**

#### **Модуль 1: Управление токенами**
```
Функции:
- Эмиссия новых токенов
- Сжигание токенов
- Замораживание/размораживание токенов
- Делегирование голосов
- Настройка прав доступа

Настройки:
- Максимальное количество токенов
- Минимальный баланс для голосования
- Период блокировки токенов
- Комиссии за операции
```

#### **Модуль 2: Система голосования**
```
Функции:
- Создание различных типов предложений
- Настройка параметров голосования
- Автоматическое выполнение решений
- Отмена предложений
- Делегирование голосов

Настройки:
- Кворум для разных типов решений
- Период голосования
- Задержка выполнения
- Порог для создания предложений
```

#### **Модуль 3: Мультиподпись**
```
Функции:
- Настройка количества подписей
- Управление подписантами
- Временные ограничения
- Отмена подписей
- Автоматическое выполнение

Настройки:
- Количество требуемых подписей
- Список авторизованных подписантов
- Время действия подписей
- Типы операций, требующие мультиподписи
```

#### **Модуль 4: Финансовое управление**
```
Функции:
- Управление балансами
- Распределение дивидендов
- Инвестирование средств
- Конвертация валют
- Управление портфелем

Настройки:
- Автоматическое распределение дивидендов
- Инвестиционные лимиты
- Валютные пары для конвертации
- Комиссии за операции
```

#### **Модуль 5: Участие в других DLE**
```
Функции:
- Покупка токенов других DLE
- Голосование в других DLE
- Управление портфелем участий
- Автоматическое голосование
- Отчетность по участиям

Настройки:
- Лимиты на участие в других DLE
- Стратегии голосования
- Автоматические действия
- Уведомления о важных событиях
```

#### **Модуль 6: Коммуникация**
```
Функции:
- Управление сообщениями
- Настройка уведомлений
- Автоматические ответы
- Интеграция с внешними сервисами
- Архив коммуникаций

Настройки:
- Автоматические ответы
- Фильтры сообщений
- Интеграции (email, telegram, slack)
- Шаблоны ответов
```

#### **Модуль 7: Безопасность**
```
Функции:
- Многофакторная аутентификация
- Временные блокировки
- Аудит операций
- Восстановление доступа
- Мониторинг безопасности

Настройки:
- Уровни безопасности
- Временные ограничения
- Список доверенных адресов
- Автоматические блокировки
```

#### **Модуль 8: Отчетность**
```
Функции:
- Генерация финансовых отчетов
- Отчеты о голосованиях
- Отчеты об участиях
- Налоговая отчетность
- Экспорт данных

Настройки:
- Периодичность отчетов
- Форматы экспорта
- Автоматическая отправка
- Шаблоны отчетов
```

## 🔄 Интеграция модулей

### **Связи между модулями:**
```
Управление токенами ↔ Система голосования
Финансовое управление ↔ Участие в других DLE
Мультиподпись ↔ Все критические операции
Безопасность ↔ Все модули
Отчетность ↔ Все модули
Коммуникация ↔ Все модули
```

### **Настройка модулей:**
```
1. Активация/деактивация модулей
2. Настройка параметров каждого модуля
3. Установка связей между модулями
4. Тестирование функциональности
5. Развертывание в production
```

## 🎯 Ключевые особенности DLE

### **1. Единый идентификатор:**
- Адрес смарт-контракта = ИНН организации
- Все функции доступны через один адрес
- Полная прозрачность всех операций

### **2. Автоматизация:**
- Автоматическое выполнение решений
- Автоматическое распределение дивидендов
- Автоматическая отчетность

### **3. Безопасность:**
- Мультиподпись для критических операций
- Временные задержки для важных решений
- Полный аудит в блокчейне

### **4. Масштабируемость:**
- Участие в неограниченном количестве других DLE
- Настраиваемые параметры для разных типов операций
- Модульная архитектура для добавления новых функций

## 🏆 Преимущества DLE над традиционным АО

### **Эффективность:**
- Мгновенные платежи и переводы
- Автоматическое выполнение решений
- Снижение бюрократических процедур

### **Прозрачность:**
- Все операции видны в блокчейне
- Невозможность подделки документов
- Полная история всех действий

### **Глобальность:**
- Работа без границ
- Участие в международных проектах
- Мультивалютные операции

### **Инновационность:**
- Интеграция с DeFi протоколами
- Участие в DAO экосистеме
- Доступ к новым финансовым инструментам