Update README files for local-first architecture and production deploy.
Document VITE_DATA_MODE, frontend layers, containerized deploy flow, and refresh deploy guide with git clone, build flags, and troubleshooting. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Cursor
@@ -1,19 +1,34 @@
|
||||
# Social Graph Builder
|
||||
|
||||
Построитель социального графа: импорт контактов, визуализация связей, CRUD.
|
||||
Построитель социального графа: импорт контактов, визуализация связей, CRUD, карта сети.
|
||||
|
||||
По умолчанию приложение работает в режиме **local-first**: данные хранятся в браузере (IndexedDB), backend для обычной работы не обязателен.
|
||||
|
||||
## Стек
|
||||
|
||||
| Слой | Технология |
|
||||
|------|-----------|
|
||||
| Backend API | Django 4.2 + Django REST Framework |
|
||||
| База данных | SQLite |
|
||||
| Frontend | Vue.js 3 + Vite |
|
||||
| Граф | vis-network |
|
||||
| Состояние | Pinia |
|
||||
| Запуск | Docker Compose |
|
||||
| Frontend | Vue 3 + Vite + Pinia |
|
||||
| Локальное хранилище | IndexedDB (Dexie) |
|
||||
| Backend API (опционально) | Django 4.2 + DRF |
|
||||
| БД backend | SQLite |
|
||||
| Граф / карта | vis-network |
|
||||
| Dev-запуск | Docker Compose |
|
||||
| Production | Docker Compose + прокси на хосте |
|
||||
|
||||
## Быстрый старт
|
||||
## Режимы данных
|
||||
|
||||
Переключатель: `VITE_DATA_MODE` (задаётся при **сборке** фронта).
|
||||
|
||||
| Режим | Описание |
|
||||
|-------|----------|
|
||||
| `local` (по умолчанию) | IndexedDB в браузере, максимум конфиденциальности |
|
||||
| `remote` | Django API + SQLite на сервере |
|
||||
| `hybrid` | зарезервирован для будущей синхронизации |
|
||||
|
||||
Пример для production: см. `deploy/.env.prod.example`.
|
||||
|
||||
## Быстрый старт (разработка)
|
||||
|
||||
```bash
|
||||
git clone <repo>
|
||||
@@ -21,10 +36,51 @@ cd social-graph
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
- Frontend: http://localhost:5173
|
||||
- Backend API: http://localhost:8000/api/
|
||||
- Frontend (Vite): http://localhost:5173
|
||||
- Backend API: http://localhost:8000/api/ (для `remote` или legacy)
|
||||
|
||||
## API endpoints
|
||||
Страницы: `/graph`, `/map`, `/contacts`, `/import`.
|
||||
|
||||
## Архитектура frontend
|
||||
|
||||
```text
|
||||
views / components
|
||||
↓
|
||||
Pinia store (orchestration)
|
||||
↓
|
||||
application/usecases
|
||||
↓
|
||||
infrastructure/repositories → local (IndexedDB) | remote (REST)
|
||||
↓
|
||||
changelog + syncAdapter (noop, подготовка к sync)
|
||||
```
|
||||
|
||||
## Структура проекта
|
||||
|
||||
```text
|
||||
social-graph/
|
||||
├── backend/ # Django API (опционально)
|
||||
│ ├── contacts/
|
||||
│ ├── config/
|
||||
│ ├── Dockerfile # dev
|
||||
│ └── Dockerfile.prod # gunicorn
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── application/usecases/
|
||||
│ │ ├── infrastructure/ # db, repositories, sync, config
|
||||
│ │ ├── domain/
|
||||
│ │ ├── views/ # Graph, NetworkMap, Contacts, Import
|
||||
│ │ ├── stores/
|
||||
│ │ └── components/
|
||||
│ ├── Dockerfile # dev (Vite)
|
||||
│ ├── Dockerfile.prod # build + nginx
|
||||
│ └── nginx.conf
|
||||
├── deploy/ # production: Apache, env, инструкции
|
||||
├── docker-compose.yml # dev
|
||||
└── docker-compose.prod.yml # production
|
||||
```
|
||||
|
||||
## API endpoints (backend, режим remote)
|
||||
|
||||
| Метод | URL | Описание |
|
||||
|-------|-----|----------|
|
||||
@@ -32,65 +88,36 @@ docker compose up --build
|
||||
| GET/PATCH/DELETE | `/api/contacts/{id}/` | Контакт по ID |
|
||||
| GET/POST | `/api/relations/` | Список / создание связей |
|
||||
| DELETE | `/api/relations/{id}/` | Удалить связь |
|
||||
| GET | `/api/graph/` | Граф (nodes + edges для vis.js) |
|
||||
| GET | `/api/graph/` | Граф для vis.js |
|
||||
| GET | `/api/network-map-graph/` | Граф карты сети |
|
||||
| GET | `/api/relation-types/` | Типы связей |
|
||||
| POST | `/api/import/` | Импорт CSV/JSON |
|
||||
| GET | `/api/network-map-choices/` | Справочники карты |
|
||||
| POST | `/api/import/` | Импорт CSV/JSON (legacy) |
|
||||
|
||||
## Формат CSV для импорта
|
||||
В режиме `local` импорт и бэкап выполняются в браузере (экран **Импорт**).
|
||||
|
||||
```csv
|
||||
name,email,phone,organization,position,notes
|
||||
Иван Иванов,ivan@example.com,+7-900-000-0001,ООО Ромашка,Директор,
|
||||
Мария Петрова,maria@example.com,+7-900-000-0002,Газпром,Аналитик,
|
||||
```
|
||||
## Импорт и бэкап (local-first)
|
||||
|
||||
## Формат JSON для импорта
|
||||
- **CSV / JSON** — экран «Импорт», парсинг на клиенте.
|
||||
- **Экспорт / импорт бэкапа** — JSON или зашифрованный `.sgpkg` (WebCrypto, пароль опционален).
|
||||
|
||||
```json
|
||||
[
|
||||
{"name": "Иван Иванов", "email": "ivan@example.com", "organization": "ООО Ромашка"},
|
||||
{"name": "Мария Петрова", "phone": "+7-900-000-0002"}
|
||||
]
|
||||
```
|
||||
## Production
|
||||
|
||||
## Структура проекта
|
||||
|
||||
```
|
||||
social-graph/
|
||||
├── backend/
|
||||
│ ├── config/ # Django settings, urls
|
||||
│ ├── contacts/ # models, serializers, views, urls
|
||||
│ ├── manage.py
|
||||
│ ├── requirements.txt
|
||||
│ └── Dockerfile
|
||||
├── frontend/
|
||||
│ ├── src/
|
||||
│ │ ├── views/ # GraphView, ContactsView, ContactDetailView, ImportView
|
||||
│ │ ├── components/ # ContactForm
|
||||
│ │ ├── stores/ # Pinia store (contacts)
|
||||
│ │ ├── router/ # Vue Router
|
||||
│ │ ├── api.js # Axios instance
|
||||
│ │ └── App.vue
|
||||
│ ├── vite.config.js
|
||||
│ └── Dockerfile
|
||||
└── docker-compose.yml
|
||||
```
|
||||
|
||||
## Production (Docker + прокси на хосте)
|
||||
|
||||
См. [deploy/README.md](deploy/README.md).
|
||||
|
||||
Кратко:
|
||||
Подробно: [deploy/README.md](deploy/README.md).
|
||||
|
||||
```bash
|
||||
git clone <repo> /opt/social-graph && cd /opt/social-graph
|
||||
cp deploy/.env.prod.example deploy/.env.prod
|
||||
docker compose -f docker-compose.prod.yml --env-file deploy/.env.prod up -d frontend
|
||||
# прокси на хосте → http://127.0.0.1:8080 (см. deploy/apache/social-graph.conf)
|
||||
docker compose -f docker-compose.prod.yml --env-file deploy/.env.prod up -d --build frontend
|
||||
# прокси на хосте → http://127.0.0.1:8080
|
||||
```
|
||||
|
||||
Схема: прокси на хосте (Apache/nginx) → контейнер frontend (nginx); backend — только при `VITE_DATA_MODE=remote`.
|
||||
|
||||
## Запуск без Docker
|
||||
|
||||
**Backend:**
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
pip install -r requirements.txt
|
||||
@@ -99,20 +126,31 @@ python manage.py runserver
|
||||
```
|
||||
|
||||
**Frontend:**
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
> В `vite.config.js` прокси настроен на `http://backend:8000`.
|
||||
> При локальном запуске без Docker замените на `http://localhost:8000`.
|
||||
> В `vite.config.js` прокси `/api` указывает на `http://backend:8000`.
|
||||
> Без Docker замените на `http://localhost:8000`.
|
||||
|
||||
## Планируемые фичи (следующие итерации)
|
||||
Для local-first backend не нужен.
|
||||
|
||||
## Тесты
|
||||
|
||||
```bash
|
||||
cd frontend && npm test
|
||||
# или в контейнере:
|
||||
docker compose exec frontend npm test -- --run
|
||||
```
|
||||
|
||||
## Планируемые фичи
|
||||
|
||||
- [ ] Авторизация (Django auth + JWT)
|
||||
- [ ] Теги/группы контактов
|
||||
- [ ] Экспорт в CSV/JSON
|
||||
- [ ] Синхронизация и shared-workspace
|
||||
- [ ] Поиск по организации и должности
|
||||
- [ ] История изменений контакта
|
||||
- [ ] Импорт из vCard (.vcf)
|
||||
|
||||
Reference in New Issue
Block a user