docs: add GREENFOOD District Protocol v1 (IndustryOps/Supply-Chain)

docs/foundation/GREENFOOD_District_Protocol_v1.md

@@ -0,0 +1,478 @@
+# 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
+