### 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:** ```go 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 тесты переходов:** ```go 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** - организация/компания ```go 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** - пользователь системы ```go 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** - место хранения ```go 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** - схема помещения из редактора ```go 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** - резервирование мест ```go 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** - размеры в сантиметрах ```go type Dimensions struct { Length float64 `json:"length"` Width float64 `json:"width"` Height float64 `json:"height"` } ``` **StorageConditions** - условия хранения ```go 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** - правила размещения товаров ```go 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 - основной сервис мест хранения **Интерфейс:** ```go 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 - работа со схемами помещений **Интерфейс:** ```go 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-кодов **Интерфейс:** ```go 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** ```go 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** ```go 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 Ключевые индексы для производительности ```sql -- Основные индексы 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 Переменные окружения ```bash # 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.