aep/second-mind-aep
1
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

update documentation

Browse Source
This commit is contained in:
andrey.epifantsev
2025-08-26 20:50:21 +04:00
parent 1882f82596
commit f663ff286d
7 changed files with 580 additions and 80 deletions
Download Patch File Download Diff File Expand all files Collapse all files

420
💡 Идеи/💡 Проекты/ERP для малых производств/Архитектура-MVP.md
View File

@@ -2,18 +2,34 @@
## 🏗️ Общая архитектура
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ React PWA │ │ Go Backend │ │ PostgreSQL │
│ (Frontend) │◄──►│ (API) │◄──►│ (Database) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ QR Scanner │ │ PDF Generator │
│ (Camera) │ │ (Labels) │
└─────────────────┘ └─────────────────┘
```mermaid
graph TB
subgraph "Frontend"
A[Angular PWA]
B[QR Scanner]
end
subgraph "Backend Services"
C[Go Core Service]
D[Python Document Service]
end
subgraph "Infrastructure"
E[PostgreSQL]
F[Redis Cache]
end
A <--> C
B --> A
C <--> E
C <--> D
D <--> F
style A fill:#ff9999
style C fill:#99ccff
style D fill:#99ff99
style E fill:#ffcc99
style F fill:#cc99ff
```
---
@@ -21,29 +37,102 @@
## 🛠️ Технологический стек
### Backend (Go)
- **Framework:** Gin или Echo
- **Framework:** Gin (легкий и быстрый)
- **Database:** PostgreSQL
- **Authentication:** JWT
- **Validation:** validator
- **PDF Generation:** wkhtmltopdf или gofpdf
- **Inter-service Communication:** gRPC + Protocol Buffers
- **API Documentation:** Swagger/OpenAPI
### Frontend (React PWA)
- **Framework:** React 18
- **Build Tool:** Vite
- **PWA:** Workbox
- **QR Scanner:** react-qr-reader
- **UI:** Tailwind CSS или Material-UI
### Frontend (Angular PWA)
- **Framework:** Angular 17+
- **Build Tool:** Angular CLI
- **PWA:** @angular/service-worker
- **QR Scanner:** @zxing/ngx-scanner
- **UI:** Angular Material + Tailwind CSS
- **State Management:** NgRx (для сложной логики)
### Document Service (Python)
- **Framework:** FastAPI (быстрый, автоматическая документация)
- **PDF Generation:** reportlab + weasyprint
- **Office Documents:** python-docx, openpyxl
- **Templates:** Jinja2
- **Caching:** Redis
- **Inter-service Communication:** gRPC
### Infrastructure
- **Containerization:** Docker
- **Deployment:** Docker Compose
- **Security:** HTTPS, CORS
- **Monitoring:** Structured logging
- **Orchestration:** Docker Compose
- **Inter-service Communication:** gRPC + Protocol Buffers
- **API Gateway:** Traefik (опционально)
- **Security:** HTTPS, CORS, JWT
- **Monitoring:** Structured logging + Prometheus
---
## 📊 Структура базы данных
### ER-диаграмма
```mermaid
erDiagram
organizations {
uuid id PK
varchar name
varchar type
jsonb settings
timestamp created_at
}
users {
uuid id PK
uuid organization_id FK
varchar email
varchar role
timestamp created_at
}
storage_locations {
uuid id PK
uuid organization_id FK
uuid parent_id FK
varchar name
varchar address
varchar type
jsonb coordinates
varchar qr_code
timestamp created_at
}
items {
uuid id PK
uuid organization_id FK
varchar name
text description
varchar category
timestamp created_at
}
item_placements {
uuid id PK
uuid organization_id FK
uuid item_id FK
uuid location_id FK
integer quantity
timestamp created_at
}
organizations ||--o{ users : "has"
organizations ||--o{ storage_locations : "has"
organizations ||--o{ items : "has"
organizations ||--o{ item_placements : "has"
storage_locations ||--o{ storage_locations : "parent-child"
storage_locations ||--o{ item_placements : "contains"
items ||--o{ item_placements : "placed_in"
```
### Основные таблицы
```sql
@@ -103,51 +192,156 @@ CREATE TABLE item_placements (
## 🔌 API Endpoints
### Аутентификация
### Core Service (Go) - REST API
```
# Аутентификация
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
```
### Document Service (Python) - REST API
```
# Документы
POST /api/documents/generate-pdf
POST /api/documents/generate-excel
GET /api/documents/:id/status
GET /api/documents/:id/download
# Шаблоны документов
GET /api/templates
POST /api/templates
PUT /api/templates/:id
DELETE /api/templates/:id
```
## 🔄 Межсервисная коммуникация
### gRPC Services
#### Core Service → Document Service
```protobuf
service DocumentService {
rpc GenerateQRCode(QRCodeRequest) returns (QRCodeResponse);
rpc GenerateReport(ReportRequest) returns (ReportResponse);
rpc GetDocumentStatus(StatusRequest) returns (StatusResponse);
}
```
#### Document Service → Core Service
```protobuf
service CoreService {
rpc GetLocationData(LocationRequest) returns (LocationResponse);
rpc GetItemData(ItemRequest) returns (ItemResponse);
rpc ValidateTemplate(TemplateRequest) returns (TemplateResponse);
}
```
### События (Event-Driven)
```protobuf
message DocumentEvent {
string event_type; // "qr_generated", "report_ready"
string document_id;
string organization_id;
google.protobuf.Timestamp timestamp;
}
```
## 🔄 Диаграммы последовательности
### Генерация QR-кода
```mermaid
sequenceDiagram
participant F as Frontend
participant C as Core Service
participant D as Document Service
participant R as Redis
F->>C: POST /api/locations/:id/qr-code
C->>D: gRPC GenerateQRCode()
D->>D: Generate QR code
D->>R: Cache document
D->>C: Return document URL
C->>F: Return QR code data
```
### Размещение товара
```mermaid
sequenceDiagram
participant U as User
participant F as Frontend
participant C as Core Service
participant DB as Database
U->>F: Scan QR code
F->>F: Decode location ID
F->>C: GET /api/locations/:id
C->>DB: Query location
DB->>C: Return location data
C->>F: Return location info
F->>U: Show location details
U->>F: Select item & quantity
F->>C: POST /api/operations/place-item
C->>DB: Create placement
DB->>C: Confirm placement
C->>F: Return success
F->>U: Show confirmation
```
### Поиск товара
```mermaid
sequenceDiagram
participant U as User
participant F as Frontend
participant C as Core Service
participant R as Redis
participant DB as Database
U->>F: Search query
F->>C: GET /api/operations/search?q=query
C->>R: Check cache
alt Cache hit
R->>C: Return cached results
else Cache miss
C->>DB: Search items & locations
DB->>C: Return results
C->>R: Cache results
end
C->>F: Return search results
F->>U: Display results
```
---
## 🔐 Безопасность
@@ -194,23 +388,39 @@ POST /api/templates/:id/apply
```yaml
version: '3.8'
services:
backend:
build: ./backend
# Core Service (Go)
core-service:
build: ./core-service
ports:
- "8080:8080"
environment:
- DB_HOST=postgres
- JWT_SECRET=your-secret
- DOC_SERVICE_URL=http://doc-service:8000
depends_on:
- postgres
- redis
# Document Service (Python)
doc-service:
build: ./doc-service
ports:
- "8000:8000"
environment:
- REDIS_URL=redis://redis:6379
- CORE_SERVICE_URL=http://core-service:8080
depends_on:
- redis
# Frontend (Angular)
frontend:
build: ./frontend
ports:
- "3000:80"
depends_on:
- backend
- core-service
# Database
postgres:
image: postgres:15
environment:
@@ -220,26 +430,134 @@ services:
volumes:
- postgres_data:/var/lib/postgresql/data
# Cache
redis:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
- redis_data:/data
# API Gateway (опционально)
traefik:
image: traefik:v2.10
command:
- --api.insecure=true
- --providers.docker=true
ports:
- "80:80"
- "8081:8080"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
volumes:
postgres_data:
redis_data:
```
### Структура проекта
```mermaid
graph TD
A[erp-mvp/] --> B[core-service/]
A --> C[doc-service/]
A --> D[frontend/]
A --> E[proto/]
A --> F[docker-compose.yml]
B --> B1[cmd/]
B --> B2[internal/]
B --> B3[pkg/]
B --> B4[proto/]
B --> B5[Dockerfile]
C --> C1[app/]
C --> C2[templates/]
C --> C3[proto/]
C --> C4[Dockerfile]
D --> D1[src/]
D --> D2[angular.json]
D --> D3[Dockerfile]
E --> E1[core.proto]
E --> E2[document.proto]
E --> E3[events.proto]
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#e8f5e8
style D fill:#fff3e0
style E fill:#fce4ec
```
---
## 📚 Конкретные библиотеки и фреймворки
### Core Service (Go)
```go
// Основные зависимости
go.mod:
- github.com/gin-gonic/gin v1.9.1 // HTTP framework
- github.com/golang-jwt/jwt/v5 v5.0.0 // JWT authentication
- github.com/lib/pq v1.10.9 // PostgreSQL driver
- github.com/go-playground/validator/v10 // Validation
- google.golang.org/grpc v1.58.0 // gRPC client/server
- github.com/swaggo/gin-swagger v1.6.0 // API documentation
- github.com/redis/go-redis/v9 v9.2.1 // Redis client
```
### Document Service (Python)
```python
# requirements.txt
fastapi==0.104.1 # Web framework
uvicorn==0.24.0 # ASGI server
reportlab==4.0.4 # PDF generation
weasyprint==60.1 # HTML to PDF
python-docx==1.1.0 # Word documents
openpyxl==3.1.2 # Excel files
jinja2==3.1.2 # Templates
redis==5.0.1 # Redis client
grpcio==1.59.0 # gRPC
protobuf==4.24.4 # Protocol Buffers
pydantic==2.4.2 # Data validation
```
### Frontend (Angular)
```json
// package.json
{
"dependencies": {
"@angular/core": "^17.0.0",
"@angular/material": "^17.0.0",
"@angular/service-worker": "^17.0.0",
"@zxing/ngx-scanner": "^3.0.0",
"@ngrx/store": "^17.0.0",
"@ngrx/effects": "^17.0.0",
"tailwindcss": "^3.3.0",
"rxjs": "^7.8.0"
}
}
```
## 📊 Мониторинг
### Логирование
- Structured JSON логи
- Уровни: DEBUG, INFO, WARN, ERROR
- Correlation ID для отслеживания запросов
- **Go:** logrus или zerolog для structured logging
- **Python:** structlog для structured logging
- **Frontend:** Angular logging service
- Correlation ID для отслеживания запросов через все сервисы
### Метрики
- Время отклика API
- Количество ошибок
- Активные пользователи
- Операции в день
- **Prometheus** для сбора метрик
- **Grafana** для визуализации
- Время отклика API по сервисам
- Количество ошибок и их типы
- Активные пользователи и операции
### Алерты
- Высокое время отклика (>500ms)
- Высокий процент ошибок (>5%)
- Недоступность сервиса
- Недоступность сервисов
- Проблемы с генерацией документов