refactor documentation

2025-08-26 20:39:12 +04:00
parent 76dd059647
commit 1882f82596
12 changed files with 965 additions and 2130 deletions
--- a/производств/Архитектура-MVP.md
+++ b/производств/Архитектура-MVP.md
@@ -0,0 +1,245 @@
+# Архитектура MVP: ERP для мастеров
+
+## 🏗️ Общая архитектура
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   React PWA     │    │   Go Backend    │    │   PostgreSQL    │
+│   (Frontend)    │◄──►│   (API)         │◄──►│   (Database)    │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+         │                       │
+         │                       │
+         ▼                       ▼
+┌─────────────────┐    ┌─────────────────┐
+│   QR Scanner    │    │   PDF Generator │
+│   (Camera)      │    │   (Labels)      │
+└─────────────────┘    └─────────────────┘
+```
+
+---
+
+## 🛠️ Технологический стек
+
+### Backend (Go)
+- **Framework:** Gin или Echo
+- **Database:** PostgreSQL
+- **Authentication:** JWT
+- **Validation:** validator
+- **PDF Generation:** wkhtmltopdf или gofpdf
+
+### Frontend (React PWA)
+- **Framework:** React 18
+- **Build Tool:** Vite
+- **PWA:** Workbox
+- **QR Scanner:** react-qr-reader
+- **UI:** Tailwind CSS или Material-UI
+
+### Infrastructure
+- **Containerization:** Docker
+- **Deployment:** Docker Compose
+- **Security:** HTTPS, CORS
+- **Monitoring:** Structured logging
+
+---
+
+## 📊 Структура базы данных
+
+### Основные таблицы
+
+```sql
+-- Организации
+CREATE TABLE organizations (
+    id UUID PRIMARY KEY,
+    name VARCHAR(255) NOT NULL,
+    type VARCHAR(100),
+    settings JSONB,
+    created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Пользователи
+CREATE TABLE users (
+    id UUID PRIMARY KEY,
+    organization_id UUID REFERENCES organizations(id),
+    email VARCHAR(255) UNIQUE NOT NULL,
+    role VARCHAR(50) DEFAULT 'user',
+    created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Места хранения
+CREATE TABLE storage_locations (
+    id UUID PRIMARY KEY,
+    organization_id UUID REFERENCES organizations(id),
+    parent_id UUID REFERENCES storage_locations(id),
+    name VARCHAR(255) NOT NULL,
+    address VARCHAR(100) NOT NULL,
+    type VARCHAR(50) NOT NULL,
+    coordinates JSONB,
+    qr_code VARCHAR(255),
+    created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Товары
+CREATE TABLE items (
+    id UUID PRIMARY KEY,
+    organization_id UUID REFERENCES organizations(id),
+    name VARCHAR(255) NOT NULL,
+    description TEXT,
+    category VARCHAR(100),
+    created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- Размещение товаров
+CREATE TABLE item_placements (
+    id UUID PRIMARY KEY,
+    organization_id UUID REFERENCES organizations(id),
+    item_id UUID REFERENCES items(id),
+    location_id UUID REFERENCES storage_locations(id),
+    quantity INTEGER DEFAULT 1,
+    created_at TIMESTAMP DEFAULT NOW()
+);
+```
+
+---
+
+## 🔌 API Endpoints
+
+### Аутентификация
+```
+POST   /api/auth/login
+POST   /api/auth/register
+POST   /api/auth/refresh
+```
+
+### Организации
+```
+GET    /api/organizations/:id
+PUT    /api/organizations/:id
+```
+
+### Места хранения
+```
+GET    /api/locations
+POST   /api/locations
+GET    /api/locations/:id
+PUT    /api/locations/:id
+DELETE /api/locations/:id
+POST   /api/locations/:id/qr-code
+```
+
+### Товары
+```
+GET    /api/items
+POST   /api/items
+GET    /api/items/:id
+PUT    /api/items/:id
+DELETE /api/items/:id
+```
+
+### Операции
+```
+POST   /api/operations/place-item
+POST   /api/operations/move-item
+GET    /api/operations/search
+```
+
+### Шаблоны
+```
+GET    /api/templates
+POST   /api/templates/:id/apply
+```
+
+---
+
+## 🔐 Безопасность
+
+### Аутентификация
+- JWT токены с refresh механизмом
+- Organization-scope на всех запросах
+- Middleware для проверки прав доступа
+
+### Валидация данных
+- Входная валидация всех параметров
+- SQL injection protection через prepared statements
+- XSS protection в frontend
+
+### HTTPS
+- Обязательное использование HTTPS
+- Secure cookies для JWT
+- CORS настройки для PWA
+
+---
+
+## 📱 PWA Особенности
+
+### Service Worker
+- Кэширование статических ресурсов
+- Offline fallback для базовых функций
+- Background sync для операций
+
+### QR Scanner
+- Использование WebRTC для доступа к камере
+- Real-time распознавание QR-кодов
+- Fallback на ручной ввод
+
+### Установка
+- Manifest для установки как нативное приложение
+- Splash screen и иконки
+- Автоматические обновления
+
+---
+
+## 🚀 Развертывание
+
+### Docker Compose
+```yaml
+version: '3.8'
+services:
+  backend:
+    build: ./backend
+    ports:
+      - "8080:8080"
+    environment:
+      - DB_HOST=postgres
+      - JWT_SECRET=your-secret
+    depends_on:
+      - postgres
+
+  frontend:
+    build: ./frontend
+    ports:
+      - "3000:80"
+    depends_on:
+      - backend
+
+  postgres:
+    image: postgres:15
+    environment:
+      - POSTGRES_DB=erp_mvp
+      - POSTGRES_USER=erp_user
+      - POSTGRES_PASSWORD=erp_pass
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:
+```
+
+---
+
+## 📊 Мониторинг
+
+### Логирование
+- Structured JSON логи
+- Уровни: DEBUG, INFO, WARN, ERROR
+- Correlation ID для отслеживания запросов
+
+### Метрики
+- Время отклика API
+- Количество ошибок
+- Активные пользователи
+- Операции в день
+
+### Алерты
+- Высокое время отклика (>500ms)
+- Высокий процент ошибок (>5%)
+- Недоступность сервиса