31 KiB
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
Инициализация:
- Загрузка конфигурации
- Подключение к базе данных и Redis
- Создание репозиториев
- Инициализация сервисов с зависимостями
- Настройка роутеров с 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.