gitrusprusandCursor
2a32c61934
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>
158 lines
5.3 KiB
Markdown
158 lines
5.3 KiB
Markdown
# Social Graph Builder
|
||
|
||
Построитель социального графа: импорт контактов, визуализация связей, CRUD, карта сети.
|
||
|
||
По умолчанию приложение работает в режиме **local-first**: данные хранятся в браузере (IndexedDB), backend для обычной работы не обязателен.
|
||
|
||
## Стек
|
||
|
||
| Слой | Технология |
|
||
|------|-----------|
|
||
| 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>
|
||
cd social-graph
|
||
docker compose up --build
|
||
```
|
||
|
||
- Frontend (Vite): http://localhost:5173
|
||
- Backend API: http://localhost:8000/api/ (для `remote` или legacy)
|
||
|
||
Страницы: `/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 | Описание |
|
||
|-------|-----|----------|
|
||
| GET/POST | `/api/contacts/` | Список / создание контактов |
|
||
| GET/PATCH/DELETE | `/api/contacts/{id}/` | Контакт по ID |
|
||
| GET/POST | `/api/relations/` | Список / создание связей |
|
||
| DELETE | `/api/relations/{id}/` | Удалить связь |
|
||
| GET | `/api/graph/` | Граф для vis.js |
|
||
| GET | `/api/network-map-graph/` | Граф карты сети |
|
||
| GET | `/api/relation-types/` | Типы связей |
|
||
| GET | `/api/network-map-choices/` | Справочники карты |
|
||
| POST | `/api/import/` | Импорт CSV/JSON (legacy) |
|
||
|
||
В режиме `local` импорт и бэкап выполняются в браузере (экран **Импорт**).
|
||
|
||
## Импорт и бэкап (local-first)
|
||
|
||
- **CSV / JSON** — экран «Импорт», парсинг на клиенте.
|
||
- **Экспорт / импорт бэкапа** — JSON или зашифрованный `.sgpkg` (WebCrypto, пароль опционален).
|
||
|
||
## Production
|
||
|
||
Подробно: [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 --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
|
||
python manage.py migrate
|
||
python manage.py runserver
|
||
```
|
||
|
||
**Frontend:**
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
> В `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)
|
||
- [ ] Теги/группы контактов
|
||
- [ ] Синхронизация и shared-workspace
|
||
- [ ] Поиск по организации и должности
|
||
- [ ] История изменений контакта
|
||
- [ ] Импорт из vCard (.vcf)
|
||
- [ ] Уведомления / дни рождения
|