microdao-daarion/docs/foundation/GREENFOOD_District_Protocol_v1.md

# GREENFOOD District Protocol v1  

## DAARION.city — IndustryOps / Supply-Chain District  

**Version:** 1.0  
**Status:** MVP Architecture  
**Scope:** Повна специфікація платформенного District GREENFOOD у межах DAARION Ontology

---

# 1. Вступ

GREENFOOD — це галузевий District типу **IndustryOps**, який об'єднує:

- крафтових виробників,
- постачальників,
- склади,
- логістичні мережі,
- торгові хаби,
- оптові та роздрібні канали,
- AI-агентів ERP та аналітики.

Цей документ визначає архітектуру, правила, протоколи та інтеграції GREENFOOD District у DAARION.city.

---

# 2. Роль GREENFOOD у DAARION Ontology

GREENFOOD є **District-платформою**:

- рівень: `district`
- parent: `root-city (DAARION)`
- orchestrator agent: **GREENFOOD ERP Agent**
- governance scope: `district:greenfood`

GREENFOOD взаємодіє з:

- City Layer (портал, публічні кімнати),
- DAIS Identity Layer,
- Rooms Layer,
- MicroDAO Layer (комітенти = виробники),
- Warehouse & Logistics Layer,
- AI Agents Layer.

Немає заздалегідь створених нод — **всі ноди реєструються вручну та динамічно**, коли виробник або інфраструктурний партнер приєднує свій сервер/пристрій.

---

# 3. Архітектура GREENFOOD District

GREENFOOD District складається з 6 модулів:

1. **Product Module**  
2. **Batch & Inventory Module**  
3. **Warehouse Module**  
4. **Logistics Module**
5. **Finance Module**
6. **Retail Hub Module**

+ **AI Automation Layer** (ERP Agent, QA Agent, Logistics Planner, Analytics Agent)

---

# 4. Ключові агенти і ролі

| Агент | Роль | Рівень |
|-------|------|--------|
| **GREENFOOD ERP Agent** | District Lead | AGENT_LEVEL_DISTRICT_LEAD |
| Producer Agent | Комітент (виробник) | AGENT_LEVEL_MEMBER / WORKER |
| Warehouse Manager Agent | Оператор складу | WORKER / CORE-TEAM |
| Logistics Agent | Планування марштрутів | WORKER |
| Retail Hub Agent | Управління роздрібом | WORKER |
| QA Agent | Сертифікація / контроль | CORE-TEAM |
| Compliance Agent | Документи, якості | CORE-TEAM |
| Analytics Agent | ML-прогнози | CORE-TEAM |

Всі агенти отримують DAIS-ідентичність.  
Жоден агент не прив'язаний до конкретної ноди за замовчуванням.

---

# 5. Supply-Chain Modules

## 5.1 Product Protocol  

Джерела:  
- Документація CRM  
- ТЗ ERP  
- Промт Комітента  
- Аналіз функцій ERP агента  

### Структура картки товару (з документів)

- Назва  
- SKU (8-значний код)  
- Виробник  
- Одиниці виміру  
- Категорія  
- Група  
- Фото / медіа  
- Складські умови  
- Термін придатності  
- Примітки  
- Ціна закупівлі / виробнича собівартість  

AI ERP Agent зобов'язаний:

- перевіряти повноту полів,
- уніфікувати назви,
- пропонувати категорії,
- генерувати SKU.

---

## 5.2 Batch Protocol (партії)

Партія — ключова сутність.

### Статуси (узгоджено з ТЗ ERP):

1. `new`  
2. `awaiting_pickup`  
3. `in_transit`  
4. `received`  
5. `rejected`  
6. `returned`  
7. `archived`

ERP Agent контролює:

- генерування партій,
- оновлення статусів,
- логіку списання,
- терміни придатності,
- відповідність товару картці.

---

## 5.3 Warehouse Protocol

GREENFOOD має три типи складів:

- **Shared Warehouse** (спільний склад District)
- **Private Warehouse** (комітент)
- **Transit Point** (логістичні хаби)

AI Warehouse Agent:

- веде облік залишків,
- синхронізує партії,
- попереджає про критичні залишки,
- перевіряє терміни придатності,
- контролює "віртуальні склади" в системі.

---

## 5.4 Logistics Protocol

Компоненти:

- планування маршрутів,
- створення накладних,
- завантаження водіїв,
- трекінг статусів,
- формування партій "до відправлення".

AI Logistics Agent:

- аналізує кількість поставок,
- підказує оптимальні маршрути,
- формує групові відправки,
- знаходить найкращий час доставки.

---

## 5.5 Retail Hub Protocol

Retail Hub = "роздрібний торговий центр".

Включає:

- модуль акцій/знижок,
- роздрібні ціни,
- автоматичні перерахунки,
- рекомендації ML.

Retail Agent:

- генерує пропозиції,
- відстежує залишки,
- оновлює роздрібні ціни залежно від оптової закупівлі + витрат.

---

## 5.6 Finance Protocol

Компоненти:

- Баланси комітентів  
- Операції: списання, зарахування  
- Резерви  
- Акцептовані накладні  
- Мультивалютність (грн, USDT, DAAR)  
- Рахунки оплат  
- Централізовані звіти  

AI Finance Agent:

- веде баланси,
- аналізує транзакції,
- робить прогноз касових потоків,
- пропонує оптимальні фінансові рішення.

---

## 5.7 Compliance Protocol (сертифікація)

Обов'язкові сутності:

- сертифікати,
- результати перевірок,
- пакети документів,
- контроль термінів дії.

AI Compliance Agent:

- нагадує про оновлення,
- валідує документи,
- веде історію.

---

# 6. AI Layer

AI Layer — серце GREENFOOD District.

## 6.1 ERP Agent  

Повна логіка описана в: "Системний промт ERP агенту".

ERP Agent робить:

- валідацію карток товарів,  
- підказки щодо категорій,
- аналіз партій,
- контроль складів,
- оптимізацію логістики,
- ризик-моніторинг партій,
- аналіз роздрібу,
- фінансові підказки.

## 6.2 Analytical Agent  

Аналітика:

- сезонність продажів,
- ML-прогнози,
- ризики порчі,
- моделі попиту.

## 6.3 Logistics Planner  

AI, що планує маршрути.

## 6.4 QA Agent  

Контроль якості продуктів.

---

# 7. City Integration

## 7.1 Greenfood Portal у City Square

- публічна кімната District  
- доступ до презентації District  
- коротка витримка цін, складів, новин

## 7.2 Greenfood Rooms

- `greenfood-lobby`  
- `greenfood-news`  
- `greenfood-help`  
- `greenfood-retail`  
- `greenfood-warehouses`  
- `greenfood-logistics`  
- приватні кімнати комітентів

## 7.3 Greenfood District Map

**Без нод.**  
Тільки логічна карта:

- склади (віртуальні і реальні)  
- офіси  
- торговий хаб  
- логістичні точки  

Мапа набуває реальних точок, коли MicroDAO-комітенти додають свої об'єкти.

---

# 8. Node Integration  

> ⚠️ Універсальна модель, без конкретних нод

GREENFOOD District підтримує **динамічне підключення нод**:

- ERP нода  
- аналітична нода  
- складські IoT ноди  
- логістичні трекери  

**Правило:**

> **Нода зʼявляється тільки після фактичного підключення користувачем / партнером.  
> Жодної статично вигаданої ноди.**

Node Protocol:

- `/nodes/register`  
- DAIS binding  
- scope: `district:greenfood`  
- capabilities (warehouse, erp, analytics, logistics)

---

# 9. Security & DAIS

GREENFOOD повністю покладається на:

- DAIS identity  
- DAIS wallet  
- DAIS keys  
- Agent Governance Protocol  
- District-level permissions  

Права комітента = права його агенту.  
Права складу = права warehouse-агента.  
Права логістики = права logistic-agent.

---

# 10. Governance

### District Lead  

— GREENFOOD ERP Agent  
Рівень доступу: `AGENT_LEVEL_DISTRICT_LEAD`.

Повноваження:

- управління District Rooms  
- управління суб-DAO виробників  
- створення warehouse agents  
- підтвердження фінансових операцій  
- створення аналітичних/логістичних агентів  

### MicroDAO (Комітенти)

Кожний виробник → microDAO типу "vendor".

### Core-team

Сюди входять:

- warehouse manager agents  
- logistics agents  
- finance agents  
- QA agents  
- analytics agents  

---

# 11. Appendix: Data Structures

## ProductCard  

| Поле | Тип | Опис |
|------|-----|------|
| id | UUID | Унікальний ідентифікатор |
| sku | VARCHAR(8) | 8-значний SKU код |
| name | TEXT | Назва товару |
| producer_id | UUID | FK → microdaos (комітент) |
| category | TEXT | Категорія товару |
| group | TEXT | Група товару |
| unit | TEXT | Одиниці виміру |
| storage_conditions | TEXT | Умови зберігання |
| shelf_life_days | INTEGER | Термін придатності (дні) |
| base_price | DECIMAL | Базова ціна |
| media_urls | JSONB | Масив URL медіа |
| metadata | JSONB | Додаткові поля |

## Batch  

| Поле | Тип | Опис |
|------|-----|------|
| id | UUID | Унікальний ідентифікатор |
| product_id | UUID | FK → products |
| quantity | DECIMAL | Кількість |
| status | ENUM | new, awaiting_pickup, in_transit, received, rejected, returned, archived |
| production_date | DATE | Дата виробництва |
| expiry_date | DATE | Дата закінчення терміну |
| warehouse_id | UUID | FK → warehouses |
| metadata | JSONB | Додаткові поля |

## Warehouse  

| Поле | Тип | Опис |
|------|-----|------|
| id | UUID | Унікальний ідентифікатор |
| name | TEXT | Назва складу |
| type | ENUM | shared, private, transit |
| owner_microdao_id | UUID | FK → microdaos |
| location | JSONB | Координати, адреса |
| capacity | DECIMAL | Ємність |
| metadata | JSONB | Додаткові поля |

## FinanceAccount  

| Поле | Тип | Опис |
|------|-----|------|
| id | UUID | Унікальний ідентифікатор |
| microdao_id | UUID | FK → microdaos |
| currency | ENUM | UAH, USDT, DAAR |
| balance | DECIMAL | Поточний баланс |
| reserved | DECIMAL | Зарезервовано |
| updated_at | TIMESTAMP | Час останнього оновлення |

## Certificate  

| Поле | Тип | Опис |
|------|-----|------|
| id | UUID | Унікальний ідентифікатор |
| product_id | UUID | FK → products |
| type | TEXT | Тип сертифікату |
| issued_at | DATE | Дата видачі |
| expires_at | DATE | Дата закінчення |
| document_url | TEXT | URL документа |
| verified | BOOLEAN | Перевірено AI |

---

# 12. Cross-References

- **DAARION_Ontology_Core_v1.md** — базова онтологія
- **District_Interface_Architecture_v1.md** — архітектура District UI
- **Agent_Governance_Protocol_v1.md** — права та ролі агентів
- **DAIS_Layer_Architecture_v1.md** — система ідентичності
- **Rooms_Layer_Architecture_v1.md** — архітектура кімнат

---

# 13. MVP Scope

## Входить до MVP:

- Реєстрація District GREENFOOD
- Portal у City Square
- District Rooms (5 базових)
- ERP Agent (базова логіка)
- Product Module
- Batch Module
- Warehouse Module (базовий)
- Finance Module (баланси)

## Не входить до MVP:

- Повна логістика з ML
- Retail Hub з рекомендаціями
- Compliance automation
- IoT інтеграція
- Multi-warehouse routing

---

**Document Status:** ✅ Ready for Implementation