cubenet_backend/SHARED_LIBS_GUIDE.md

# Shared Libraries Architecture - Абстракция для микросервисов

## 📋 Концепция

Shared libraries - это набор переиспользуемых абстракций для всех сервисов. Каждая библиотека предоставляет определенную функциональность через trait-based architecture.

## 🏗️ Структура

```
shared_libs/
├── audit_logger/           ✅ Логирование действий пользователей
│   ├── src/
│   │   ├── lib.rs
│   │   ├── models.rs       # AuditLog, ActionType, ActionStatus
│   │   ├── store.rs        # AuditStore trait, InMemoryAuditStore
│   │   └── logger.rs       # AuditLogger implementation
│   └── Cargo.toml
│
├── db_orm/                 (Планируется)
│   ├── src/
│   │   ├── lib.rs
│   │   ├── models.rs       # Shared models
│   │   ├── repository.rs   # Repository pattern
│   │   └── migrations.rs   # DB migrations
│   └── Cargo.toml
│
├── auth/                   (Планируется)
│   ├── src/
│   │   ├── lib.rs
│   │   ├── jwt.rs          # JWT token handling
│   │   └── permissions.rs  # RBAC
│   └── Cargo.toml
│
└── common/                 (Планируется)
    ├── src/
    │   ├── lib.rs
    │   ├── errors.rs       # Common error types
    │   ├── config.rs       # Configuration
    │   └── utils.rs        # Utilities
    └── Cargo.toml
```

## ✅ audit_logger (Реализовано)

### Описание
Централизованное логирование всех действий пользователей во всех микросервисах.

### Особенности
- ✅ Структурированное логирование
- ✅ Типобезопасные действия (enum ActionType)
- ✅ Отслеживание успеха/ошибок
- ✅ Метаданные (IP, User Agent, время)
- ✅ Extensible storage (trait AuditStore)
- ✅ In-memory backend для разработки

### Использование
```rust
let store = Arc::new(InMemoryAuditStore::new());
let logger = AuditLogger::new(store, "service_name");

logger.log_action(
    Some("user_id".to_string()),
    ActionType::Create,
    "resource".to_string(),
    "/endpoint".to_string(),
).await?;
```

### Расширяемость
Можно реализовать собственный backend для хранения:
- PostgreSQL backend
- Elasticsearch backend
- Kafka backend
- Другие хранилища

## 🔌 Интеграция в сервисы

### API Gateway

```rust
use audit_logger::{AuditLogger, InMemoryAuditStore};
use std::sync::Arc;

let logger = Arc::new(AuditLogger::new(
    Arc::new(InMemoryAuditStore::new()),
    "api_gateway",
));

// В handlers используйте logger
```

### API Layer

```rust
let logger = Arc::new(AuditLogger::new(
    Arc::new(InMemoryAuditStore::new()),
    "api",
));
```

### Microservices

```rust
pub struct UserServiceImpl {
    audit_logger: Arc<AuditLogger>,
}

impl UserService for UserServiceImpl {
    async fn get_users(&self, _request: Request<GetUsersRequest>) {
        self.audit_logger.log_action(
            None,
            ActionType::Read,
            "users".to_string(),
            "/GetUsers".to_string(),
        ).await.ok();
        
        // ...
    }
}
```

## 🔮 Планируемые библиотеки

### Phase 2: db_orm

**Назначение**: Абстракция для работы с БД

```rust
pub trait Repository<T>: Send + Sync {
    async fn create(&self, item: T) -> Result<T>;
    async fn read(&self, id: i32) -> Result<T>;
    async fn update(&self, item: T) -> Result<T>;
    async fn delete(&self, id: i32) -> Result<()>;
    async fn list(&self, limit: usize, offset: usize) -> Result<Vec<T>>;
}
```

**Backends**:
- SQLx для type-safe queries
- Diesel для ORM
- Sea-ORM для async ORM

### Phase 2: auth

**Назначение**: Аутентификация и авторизация

```rust
pub trait AuthProvider {
    async fn verify_token(&self, token: &str) -> Result<Claims>;
    async fn create_token(&self, user_id: &str) -> Result<String>;
    async fn has_permission(&self, user: &User, action: &str) -> Result<bool>;
}
```

**Функции**:
- JWT token handling
- RBAC (Role-Based Access Control)
- OAuth2 integration (будущее)

### Phase 2: common

**Назначение**: Общие типы и утилиты

```rust
pub enum Error {
    NotFound,
    Unauthorized,
    Forbidden,
    Internal,
    ValidationError(String),
}

pub trait Config {
    fn database_url(&self) -> String;
    fn log_level(&self) -> String;
    fn jwt_secret(&self) -> String;
}
```

## 📊 Использование в проекте

### Текущее состояние

- ✅ audit_logger включен во все сервисы
- ✅ API Gateway логирует все запросы
- ✅ API логирует все действия
- ✅ User Service логирует все операции

### Будущие интеграции

```
Phase 1 (Текущее): audit_logger
    ↓
Phase 2: db_orm + auth + common
    ↓
Phase 3: cache, metrics, tracing libraries
    ↓
Phase 4: service discovery, load balancing
```

## 🎯 Дизайн принципы

1. **Trait-based Architecture**
   - Все библиотеки предоставляют trait'ы
   - Множество реализаций (in-memory, БД, внешние сервисы)

2. **Composability**
   - Библиотеки независимы
   - Можно комбинировать в разных комбинациях

3. **Async-first**
   - Все операции асинхронные
   - Оптимизировано для высокого throughput

4. **Type Safety**
   - Использование Rust типов для безопасности
   - Compile-time checks

5. **Extensibility**
   - Легко добавлять новые backends
   - Легко добавлять новые функции

## 💼 Структурирование кода

### Правила для shared libraries

1. ✅ Каждая библиотека в отдельной папке `shared_libs/`
2. ✅ Иметь public API через `lib.rs`
3. ✅ Документировать через `README.md` в папке библиотеки
4. ✅ Использовать trait'ы для абстракции
5. ✅ Предоставлять mock/in-memory реализации
6. ✅ Писать unit тесты
7. ✅ Избегать зависимостей от конкретных сервисов

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

```
audit_logger/
├── README.md               # Документация библиотеки
├── Cargo.toml
└── src/
    ├── lib.rs              # Public API
    ├── models.rs           # Data structures
    ├── store.rs            # Storage abstraction
    ├── logger.rs           # Main implementation
    └── backends/           (Optional)
        ├── memory.rs
        ├── postgres.rs
        └── elasticsearch.rs
```

## 🔄 Workflow добавления новой библиотеки

1. Создать папку в `shared_libs/`
2. Создать `Cargo.toml` с версией из workspace
3. Написать trait'ы для абстракции
4. Реализовать in-memory backend для разработки
5. Добавить в `shared_libs/Cargo.toml` members
6. Интегрировать в сервисы
7. Документировать в README.md

## 📦 Добавление библиотеки в сервис

### 1. Обновить Cargo.toml сервиса

```toml
[dependencies]
audit_logger = { path = "../shared_libs/audit_logger" }
db_orm = { path = "../shared_libs/db_orm" }
```

### 2. Использовать в коде

```rust
use audit_logger::AuditLogger;
use db_orm::Repository;

let logger = AuditLogger::new(...);
let repo = PostgresRepository::new(...);
```

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

```bash
# Тестировать конкретную библиотеку
cargo test --package audit_logger

# Тестировать все библиотеки
cargo test --workspace

# Coverage
cargo tarpaulin --package audit_logger
```

## 📈 Масштабирование

### Для разработки
- Используйте in-memory backends
- Быстро, без внешних зависимостей
- Идеально для unit tests

### Для тестирования
- Используйте Docker containers
- PostgreSQL, Redis в containers
- Integration tests

### Для production
- Используйте production-grade backends
- PostgreSQL для данных
- Redis для cache
- Elasticsearch для поиска

## 🚀 Best Practices

1. ✅ Начните с in-memory реализации
2. ✅ Потом добавьте production backends
3. ✅ Всегда используйте trait'ы
4. ✅ Документируйте public API
5. ✅ Пишите тесты для каждой библиотеки
6. ✅ Версионируйте через workspace
7. ✅ Избегайте circular dependencies

## 📚 Документация

Каждая библиотека должна иметь:
- README.md с примерами
- Doc comments на всех public типах
- Examples в документации
- Unit tests как примеры использования

## 🔗 Связи

```
audit_logger
    ├─ используется в api_gateway
    ├─ используется в api
    └─ используется в microservices

db_orm (планируется)
    ├─ может использоваться с auth
    └─ может использовать audit_logger

auth (планируется)
    ├─ middleware в api_gateway
    └─ проверка в microservices
```

---

**Статус**: ✅ Foundation готов, готовы Phase 2 библиотеки