Files
second-mind-aep/💡 Идеи/💡 Проекты/ERP для малых производств/План-разработки-Core-Service-Go-Архитектура-и-API.md
2025-08-26 20:03:36 +04:00

31 KiB
Raw Blame History

10.1 Этапы с учетом Security подготовки

Этап 1: Инфраструктура + Security foundation (1-2 недели)

  • Настройка проекта, зависимостей, Docker
  • База данных с полями для будущего шифрования
  • Security интерфейсы (DataProtection, PasswordHasher, AuditLogger)
  • NoOp реализации для MVP
  • Базовая конфигурация и логирование
  • Middleware для аутентификации

Этап 2: Базовые сущности с Security готовностью (2-3 недели)

  • Organizations и Users (CRUD + auth)
  • Использование Security интерфейсов в репозиториях
  • Хеширование паролей (Argon2)
  • Генерация хешей для поиска (уже сейчас)
  • StorageLocations базовый CRUD
  • Простая иерархия мест
  • Генерация адресов

Этап 3: Схемы и QR-коды (2-3 недели)

  • StorageSchemas CRUD
  • Генерация QR-кодов и этикеток
  • Связывание схем с местами хранения
  • Валидация схем
  • Аудит-логирование операций

Этап 4: Поиск и аналитика (1-2 недели)

  • Поиск и фильтрация мест
  • Поиск через хеши (готовность к шифрованию)
  • Умные подсказки размещения
  • Базовая аналитика использования
  • Резервирование мест

Этап 5: Мобильные операции (1 неделя)

  • Сканирование QR-кодов
  • Offline синхронизация
  • Быстрые действия

Этап 6: Оптимизация и тестирование (1-2 недели)

  • Полное покрытие тестами (включая security моки)
  • Оптимизация производительности
  • Документация API
  • Подготовка к деплою

Этап 7: Включение шифрования (будущий, 1-2 недели)

  • Реализация AES шифрования
  • Управление ключами
  • Миграция существующих данных
  • Полный аудит безопасности

10.2 Дополнительные задачи по Security

В рамках MVP (этапы 1-6):

  • Хеширование паролей (Argon2id)
  • JWT аутентификация
  • HTTPS везде
  • Аудит-логирование доступа
  • Валидация входных данных
  • Подготовка схемы БД к шифрованию
  • Security интерфейсы

При включении шифрования (этап 7):

  • 🔄 AES-256-GCM шифрование PII
  • 🔄 Иерархия ключей по организациям
  • 🔄 Ротация ключей
  • 🔄 Миграция данных
  • 🔄 GDPR соответствие

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

Unit тесты для Security:

func TestNoOpDataProtection(t *testing.T) {
    protection := security.NewNoOpDataProtection()
    
    original := "test@example.com"
    encrypted, err := protection.Encrypt(original)
    assert.NoError(t, err)
    assert.Equal(t, original, encrypted) // NoOp возвращает как есть
    
    decrypted, err := protection.Decrypt(encrypted)
    assert.NoError(t, err)
    assert.Equal(t, original, decrypted)
}

func TestUserRepositoryWithSecurity(t *testing.T) {
    // Тест с моком security
    mockProtection := &mocks.DataProtection{}
    mockProtection.On("Hash", "test@example.com").Return("hashed_email")
    
    repo := NewUserRepository(db, mockProtection, auditLogger)
    
    user := &User{Email: "test@example.com"}
    err := repo.Create(ctx, user)
    
    assert.NoError(t, err)
    mockProtection.AssertExpectations(t)
}

Integration тесты переходов:

func TestEncryptionMigration(t *testing.T) {
    // Тест миграции с NoOp на AES
    // Создаем данные с NoOp
    // Мигрируем на AES
    // Проверяем корректность данных
}

11. Мониторинг и безопасность---

title: "Архитектура Core Service (Go)" description: "Детальный план разработки backend с Clean Architecture, API и безопасностью" tags: [architecture, backend, go, api, security, database] date: 2024-08-26

План разработки Core Service (Go): Архитектура и API

1. Архитектура проекта

1.1 Clean Architecture принципы

  • Domain Layer - бизнес-логика, независимая от внешних зависимостей
  • Infrastructure Layer - работа с базой данных, внешними API
  • Interface Layer - REST API, middleware, DTO
  • Application Layer - координация между слоями

1.2 Структура директорий

core-service/
├── cmd/server/                 # Точка входа приложения
├── internal/
│   ├── domain/                 # Бизнес-логика
│   │   ├── entities/          # Доменные сущности
│   │   ├── services/          # Бизнес-сервисы
│   │   └── repositories/      # Интерфейсы репозиториев
│   ├── infrastructure/        # Инфраструктурный слой
│   │   ├── database/          # PostgreSQL репозитории
│   │   ├── cache/             # Redis кэш
│   │   └── external/          # HTTP клиенты к Python сервису
│   ├── interfaces/            # Слой представления
│   │   ├── api/               # REST API handlers
│   │   ├── middleware/        # Аутентификация, логирование
│   │   └── dto/               # Data Transfer Objects
│   └── config/                # Конфигурация приложения
├── migrations/                # SQL миграции
└── docs/                     # OpenAPI документация

2. Доменные сущности

2.1 Основные entities

Organization - организация/компания

type Organization struct {
    ID       uuid.UUID `json:"id"`
    Name     string    `json:"name"`
    Type     string    `json:"type"`           // Тип производства
    Settings JSONB     `json:"settings"`       // Настройки адресации, QR и др.
    
    // Подготовка к будущему шифрованию
    NameEncrypted    *string `db:"name_encrypted" json:"-"`
    ContactEncrypted *string `db:"contact_encrypted" json:"-"`
    
    // timestamps, audit fields
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
}

User - пользователь системы

type User struct {
    ID             uuid.UUID `json:"id"`
    OrganizationID uuid.UUID `json:"organization_id"`
    Email          string    `json:"email"`
    FirstName      string    `json:"first_name"`
    LastName       string    `json:"last_name"`
    Role           UserRole  `json:"role"`     // owner, employee, observer
    IsActive       bool      `json:"is_active"`
    
    // Подготовка к будущему шифрованию (nullable поля)
    EmailEncrypted     *string `db:"email_encrypted" json:"-"`
    FirstNameEncrypted *string `db:"first_name_encrypted" json:"-"`
    LastNameEncrypted  *string `db:"last_name_encrypted" json:"-"`
    EmailHash          *string `db:"email_hash" json:"-"`
    
    // auth fields, timestamps
    PasswordHash   string     `json:"-"`
    LastLoginAt    *time.Time `json:"last_login_at"`
    CreatedAt      time.Time  `json:"created_at"`
    UpdatedAt      time.Time  `json:"updated_at"`
}

StorageLocation - место хранения

type StorageLocation struct {
    ID              uuid.UUID         `json:"id"`
    OrganizationID  uuid.UUID         `json:"organization_id"`
    ParentID        *uuid.UUID        `json:"parent_id"`
    Address         string            `json:"address"`        // Ш1-П2-Я3
    Name            string            `json:"name"`
    Type            LocationType      `json:"type"`           // shelf, zone, table
    Level           int               `json:"level"`          // Уровень в иерархии
    
    // Физические характеристики
    Dimensions      Dimensions        `json:"dimensions"`     // Д×Ш×В в см
    MaxWeight       float64           `json:"max_weight"`     // кг
    MaxVolume       float64           `json:"max_volume"`     // литры
    
    // Условия хранения
    StorageConditions StorageConditions `json:"storage_conditions"`
    
    // QR и схема
    QRCode          string            `json:"qr_code"`
    QRCodeData      JSONB             `json:"qr_code_data"`
    SchemaCoordinates *Coordinates    `json:"schema_coordinates"`
    
    // Статус и правила
    Status          LocationStatus    `json:"status"`         // active, reserved, maintenance
    PlacementRules  []PlacementRule   `json:"placement_rules"`
}

StorageSchema - схема помещения из редактора

type StorageSchema struct {
    ID             uuid.UUID  `json:"id"`
    OrganizationID uuid.UUID  `json:"organization_id"`
    Name           string     `json:"name"`
    Version        int        `json:"version"`
    SchemaData     SchemaData `json:"schema_data"`     // JSON из редактора
    IsActive       bool       `json:"is_active"`
}

LocationReservation - резервирование мест

type LocationReservation struct {
    ID           uuid.UUID         `json:"id"`
    LocationID   uuid.UUID         `json:"location_id"`
    UserID       uuid.UUID         `json:"user_id"`
    Type         ReservationType   `json:"type"`      // temporary, permanent, seasonal
    ReservedFrom time.Time         `json:"reserved_from"`
    ReservedTo   *time.Time        `json:"reserved_to"`
    Status       ReservationStatus `json:"status"`    // active, expired, canceled
}

2.2 Вспомогательные типы

Dimensions - размеры в сантиметрах

type Dimensions struct {
    Length float64 `json:"length"`
    Width  float64 `json:"width"`
    Height float64 `json:"height"`
}

StorageConditions - условия хранения

type StorageConditions struct {
    Temperature   *TemperatureRange `json:"temperature,omitempty"`
    Humidity      *HumidityRange    `json:"humidity,omitempty"`
    Accessibility string            `json:"accessibility"`  // easy, medium, hard
    Special       []string          `json:"special"`        // chemical, food_safe
}

PlacementRule - правила размещения товаров

type PlacementRule struct {
    Type        string      `json:"type"`        // weight_limit, item_type, frequency
    Condition   string      `json:"condition"`   // max, only, preferred
    Value       interface{} `json:"value"`
    Priority    int         `json:"priority"`
}

3. Бизнес-сервисы

3.1 LocationService - основной сервис мест хранения

Интерфейс:

type LocationService interface {
    // CRUD операции
    CreateLocation(ctx context.Context, req CreateLocationRequest) (*StorageLocation, error)
    GetLocation(ctx context.Context, id uuid.UUID) (*StorageLocation, error)
    UpdateLocation(ctx context.Context, id uuid.UUID, req UpdateLocationRequest) error
    DeleteLocation(ctx context.Context, id uuid.UUID) error
    
    // Иерархические операции
    GetLocationHierarchy(ctx context.Context, organizationID uuid.UUID) ([]*LocationNode, error)
    MoveLocation(ctx context.Context, locationID uuid.UUID, newParentID *uuid.UUID) error
    
    // Генерация адресов и QR
    GenerateAddress(ctx context.Context, location *StorageLocation) (string, error)
    GenerateQRCode(ctx context.Context, locationID uuid.UUID) (*QRCodeResult, error)
    
    // Поиск и подсказки
    SearchLocations(ctx context.Context, req SearchLocationRequest) (*SearchLocationResponse, error)
    SuggestOptimalLocation(ctx context.Context, req OptimalLocationRequest) ([]*LocationSuggestion, error)
}

Основная логика:

  • Валидация данных при создании/обновлении
  • Автоматическая генерация адресов по настройкам организации
  • Проверка правил размещения
  • Расчет оптимальных мест для размещения товаров

3.2 SchemaService - работа со схемами помещений

Интерфейс:

type SchemaService interface {
    // CRUD схем
    CreateSchema(ctx context.Context, req CreateSchemaRequest) (*StorageSchema, error)
    UpdateSchema(ctx context.Context, id uuid.UUID, req UpdateSchemaRequest) error
    GetActiveSchema(ctx context.Context, organizationID uuid.UUID) (*StorageSchema, error)
    
    // Операции с объектами схемы
    AddSchemaObject(ctx context.Context, schemaID uuid.UUID, object SchemaObject) error
    UpdateSchemaObject(ctx context.Context, schemaID uuid.UUID, objectID string, updates interface{}) error
    
    // Валидация и генерация
    ValidateSchema(ctx context.Context, schema *StorageSchema) (*ValidationResult, error)
    GenerateLocationsFromSchema(ctx context.Context, schemaID uuid.UUID) ([]*StorageLocation, error)
    SyncSchemaWithLocations(ctx context.Context, schemaID uuid.UUID) error
}

Основная логика:

  • Валидация корректности схемы (доступность, эргономика)
  • Автоматическая генерация мест хранения из объектов схемы
  • Синхронизация изменений схемы с местами хранения
  • Проверка правил безопасности и эргономики

3.3 QRCodeService - генерация QR-кодов

Интерфейс:

type QRCodeService interface {
    GenerateQRCode(ctx context.Context, location *StorageLocation) (*QRCodeResult, error)
    GenerateQRCodeBatch(ctx context.Context, locationIDs []uuid.UUID) ([]*QRCodeResult, error)
    ValidateQRCode(ctx context.Context, qrData string) (*QRValidationResult, error)
    DecodeQRCode(ctx context.Context, qrData string) (*QRDecodedData, error)
    GenerateLabels(ctx context.Context, req GenerateLabelsRequest) (*LabelSheet, error)
}

Основная логика:

  • Кодирование метаданных места в QR (ID, адрес, координаты, чексумма)
  • Генерация изображений QR-кодов в разных форматах
  • Создание шаблонов этикеток для печати
  • Валидация и декодирование сканированных QR

4. REST API структура

4.1 Основные группы endpoints

Authentication & Users

POST   /api/v1/auth/login
POST   /api/v1/auth/register
POST   /api/v1/auth/refresh
POST   /api/v1/users/invite
PUT    /api/v1/users/:id/role

Organizations

GET    /api/v1/organizations/:id
PUT    /api/v1/organizations/:id
GET    /api/v1/organizations/:id/settings
PUT    /api/v1/organizations/:id/settings

Storage Locations

GET    /api/v1/locations                    # Список с фильтрами
POST   /api/v1/locations                    # Создание
GET    /api/v1/locations/:id                # Детали места
PUT    /api/v1/locations/:id                # Обновление
DELETE /api/v1/locations/:id                # Удаление

GET    /api/v1/locations/hierarchy          # Дерево мест
POST   /api/v1/locations/:id/move           # Перемещение в иерархии

GET    /api/v1/locations/:id/qr-code        # Генерация QR
POST   /api/v1/locations/qr-codes/batch     # Массовая генерация QR

GET    /api/v1/locations/search             # Поиск мест
POST   /api/v1/locations/suggest            # Подсказки размещения

POST   /api/v1/locations/:id/reserve        # Резервирование
GET    /api/v1/locations/:id/reservations   # Список резерваций

Storage Schemas

GET    /api/v1/schemas                      # Список схем
POST   /api/v1/schemas                      # Создание схемы
GET    /api/v1/schemas/:id                  # Детали схемы
PUT    /api/v1/schemas/:id                  # Обновление схемы

POST   /api/v1/schemas/:id/objects          # Добавление объекта
PUT    /api/v1/schemas/:id/objects/:objId   # Обновление объекта
DELETE /api/v1/schemas/:id/objects/:objId   # Удаление объекта

POST   /api/v1/schemas/:id/validate         # Валидация схемы
POST   /api/v1/schemas/:id/generate-locations # Генерация мест из схемы
POST   /api/v1/schemas/:id/sync             # Синхронизация с местами

GET    /api/v1/schemas/:id/export/:format   # Экспорт схемы

Labels & Templates

GET    /api/v1/templates/labels             # Шаблоны этикеток
POST   /api/v1/templates/labels/generate    # Генерация этикеток

Analytics & Reports

GET    /api/v1/analytics/space-usage        # Использование пространства
GET    /api/v1/analytics/location-activity  # Активность мест
GET    /api/v1/analytics/optimization-suggestions # Предложения по оптимизации

Mobile Operations

POST   /api/v1/mobile/scan                  # Сканирование QR
GET    /api/v1/mobile/quick-actions         # Быстрые действия
POST   /api/v1/mobile/sync                  # Синхронизация offline операций

4.2 Примеры DTO структур

CreateLocationRequest

type CreateLocationRequest struct {
    ParentID          *string               `json:"parent_id"`
    Name              string                `json:"name" binding:"required,max=255"`
    Type              LocationType          `json:"type" binding:"required"`
    Dimensions        *Dimensions           `json:"dimensions"`
    MaxWeight         float64               `json:"max_weight"`
    MaxVolume         float64               `json:"max_volume"`
    StorageConditions *StorageConditions    `json:"storage_conditions"`
    PlacementRules    []PlacementRule       `json:"placement_rules"`
    SchemaCoordinates *Coordinates          `json:"schema_coordinates"`
}

LocationResponse

type LocationResponse struct {
    ID                uuid.UUID             `json:"id"`
    Address           string                `json:"address"`
    Name              string                `json:"name"`
    Type              LocationType          `json:"type"`
    Level             int                   `json:"level"`
    Parent            *LocationBrief        `json:"parent,omitempty"`
    Children          []*LocationBrief      `json:"children,omitempty"`
    Dimensions        *Dimensions           `json:"dimensions"`
    Status            LocationStatus        `json:"status"`
    QRCode            string                `json:"qr_code,omitempty"`
    SchemaCoordinates *Coordinates          `json:"schema_coordinates"`
    Stats             *LocationStats        `json:"stats,omitempty"`
    CreatedAt         time.Time             `json:"created_at"`
    UpdatedAt         time.Time             `json:"updated_at"`
}

5. База данных

5.1 Основные таблицы

organizations - организации

  • Основные поля: id, name, type, settings (JSONB)
  • Настройки адресации, QR-кодов, правил размещения

users - пользователи

  • Связь с organizations, роли, аутентификация

storage_locations - места хранения

  • Иерархическая структура через parent_id
  • JSONB поля для dimensions, storage_conditions, placement_rules
  • Индексы по organization_id, parent_id, address, qr_code

storage_schemas - схемы помещений

  • JSONB поле schema_data с данными из редактора
  • Версионирование схем

location_reservations - резервирования мест

  • Временные рамки, типы резервирования, статусы

activity_logs - логи всех операций

  • Аудит изменений, безопасность, аналитика

5.2 Ключевые индексы для производительности

-- Основные индексы
CREATE INDEX idx_storage_locations_organization_id ON storage_locations(organization_id);
CREATE INDEX idx_storage_locations_parent_id ON storage_locations(parent_id);
CREATE INDEX idx_storage_locations_address ON storage_locations(organization_id, address);
CREATE INDEX idx_storage_locations_qr_code ON storage_locations(qr_code);

-- Составные индексы для фильтрации
CREATE INDEX idx_locations_org_type_status ON storage_locations(organization_id, type, status);
CREATE INDEX idx_reservations_location_dates ON location_reservations(location_id, reserved_from, reserved_to);

5.3 Триггеры и функции

  • update_updated_at_column() - автообновление timestamps
  • Валидация иерархии мест хранения
  • Автоматическое логирование изменений

6. Middleware и безопасность

6.1 Authentication Middleware

JWT Authentication

  • Валидация JWT токенов
  • Извлечение user_id, organization_id, role из токена
  • Добавление контекста в запрос

Role-based Access Control

  • Проверка прав доступа по ролям
  • Owner - полный доступ
  • Employee - операции + просмотр
  • Observer - только просмотр

Organization Scope

  • Автоматическая фильтрация по организации
  • Предотвращение доступа к чужим данным

6.2 Дополнительные middleware

Request Logging

  • Структурированное логирование всех запросов
  • Включение user_id, organization_id в логи

Error Handling

  • Централизованная обработка ошибок
  • Panic recovery
  • Стандартизированные коды ошибок

Rate Limiting

  • Защита от злоупотреблений API
  • Разные лимиты для разных endpoint'ов

7. Конфигурация и окружение

7.1 Конфигурация приложения

Config структура:

  • Server (порт, таймауты)
  • Database (подключение, пулы соединений)
  • Redis (кэширование, сессии)
  • JWT (секретные ключи, время жизни)
  • Storage (локальное/S3 хранилище файлов)
  • External Services (URL Python сервиса)
  • Logging (уровень, формат)

Загрузка конфигурации:

  • Приоритет: переменные окружения > config.yml > дефолты
  • Валидация обязательных параметров
  • Поддержка разных окружений (dev, staging, prod)

7.2 Переменные окружения

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=password
DB_NAME=erp_masters

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT
JWT_SECRET_KEY=your-secret-key
JWT_EXPIRATION_HOURS=24

# External Services
DOCUMENT_SERVICE_URL=http://localhost:8081

8. Dependency Injection

8.1 Dependencies структура

Основные компоненты:

  • Repositories (database layer)
  • Services (business logic)
  • Infrastructure (DB, Redis, Logger)
  • Configuration

Инициализация:

  1. Загрузка конфигурации
  2. Подключение к базе данных и Redis
  3. Создание репозиториев
  4. Инициализация сервисов с зависимостями
  5. Настройка роутеров с handlers

8.2 Жизненный цикл приложения

Startup:

  • Проверка подключений к внешним сервисам
  • Выполнение миграций базы данных
  • Warmup кэшей и пулов соединений

Graceful Shutdown:

  • Завершение активных запросов
  • Закрытие соединений с базой данных
  • Flush логов

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

9.1 Стратегия тестирования

Unit Tests

  • Тестирование бизнес-логики сервисов
  • Мокирование зависимостей
  • Покрытие edge cases и error handling

Integration Tests

  • Тестирование API endpoints
  • Работа с тестовой базой данных
  • Проверка полных сценариев использования

Repository Tests

  • Тестирование SQL запросов
  • Проверка миграций и схемы БД
  • Тестирование транзакций

9.2 Test Infrastructure

Test Database

  • Автоматическое создание/очистка тестовых данных
  • Изоляция тестов друг от друга
  • Использование фикстур для стандартных данных

Mocks & Stubs

  • Мокирование внешних сервисов
  • Симуляция различных ответов от Python сервиса
  • Тестирование fallback сценариев

10. Мониторинг и логирование

10.1 Структурированное логирование

Уровни логирования:

  • ERROR - критические ошибки
  • WARN - предупреждения и неоптимальные ситуации
  • INFO - основные операции и бизнес-события
  • DEBUG - детальная информация для отладки

Контекст в логах:

  • request_id для трассировки запросов
  • user_id и organization_id для аудита
  • Время выполнения операций
  • Метаданные запросов и ответов

10.2 Метрики и мониторинг

Application Metrics

  • Количество запросов по endpoint'ам
  • Время ответа API
  • Количество ошибок по типам
  • Использование ресурсов (CPU, память, соединения БД)

Business Metrics

  • Количество активных организаций
  • Количество созданных мест хранения
  • Частота использования различных функций
  • Конверсия новых пользователей

11. Производительность и масштабирование

11.1 Оптимизация базы данных

Индексирование

  • Композитные индексы для частых запросов
  • Частичные индексы для фильтрации по статусам
  • Индексы на JSONB поля для поиска по метаданным

Query Optimization

  • Использование prepared statements
  • Батчинг операций создания/обновления
  • Пагинация для больших списков

11.2 Кэширование

Redis Cache

  • Кэширование схем организаций
  • Кэширование иерархии мест хранения
  • Кэширование результатов поиска
  • TTL стратегии для разных типов данных

Application Cache

  • In-memory кэш для справочников
  • Кэширование сгенерированных QR-кодов
  • Кэш результатов валидации

12. План разработки по этапам

Этап 1: Инфраструктура (1-2 недели)

  • Настройка проекта, зависимостей, Docker
  • База данных, миграции, подключения
  • Базовая конфигурация и логирование
  • Middleware для аутентификации

Этап 2: Базовые сущности (2-3 недели)

  • Organizations и Users (CRUD + auth)
  • StorageLocations базовый CRUD
  • Простая иерархия мест
  • Генерация адресов

Этап 3: Схемы и QR-коды (2-3 недели)

  • StorageSchemas CRUD
  • Генерация QR-кодов и этикеток
  • Связывание схем с местами хранения
  • Валидация схем

Этап 4: Поиск и аналитика (1-2 недели)

  • Поиск и фильтрация мест
  • Умные подсказки размещения
  • Базовая аналитика использования
  • Резервирование мест

Этап 5: Мобильные операции (1 неделя)

  • Сканирование QR-кодов
  • Offline синхронизация
  • Быстрые действия

Этап 6: Оптимизация и тестирование (1-2 недели)

  • Полное покрытие тестами
  • Оптимизация производительности
  • Документация API
  • Подготовка к деплою

Общая оценка: 8-13 недель разработки


Этот план обеспечивает создание масштабируемого, тестируемого и производительного core service для управления складскими помещениями с современной архитектурой и лучшими практиками разработки на Go.