trevor/links
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

+ Приведены все функции приложения в рабочий вид

Browse Source 
+ Наведен порядок в файлах проекта
+ Наведен порядок в документации
+ Настроены скрипты установки, развертки и так далее, расширен MakeFile
This commit is contained in:
Andrey K. Choi
2025-11-02 06:09:55 +09:00
parent 367e1c932e
commit 2e535513b5
6103 changed files with 7040 additions and 1027861 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
docs/COVER_OVERLAY_TESTING.md Normal file
View File

@@ -0,0 +1,108 @@
# Тестирование функциональности Cover Overlay
## Функциональность Cover Overlay
Мы добавили новую функциональность для перекрытия обложки пользователя цветным слоем с настраиваемой прозрачностью.
### Backend изменения
1. **Модель DesignSettings** (`customization/models.py`):
- `cover_overlay_enabled` - Boolean поле для включения/отключения
- `cover_overlay_color` - Hex цвет перекрытия (например #000000)
- `cover_overlay_opacity` - Float значение прозрачности от 0.0 до 1.0
2. **Сериализатор** (`customization/serializers.py`):
- Валидация hex цвета
- Валидация диапазона прозрачности
3. **API** (`api/views.py`):
- Поддержка новых полей в публичном API
### Frontend изменения
1. **Интерфейсы TypeScript**:
- Обновлены `DesignSettings` интерфейсы в `DashboardClient.tsx`
- Обновлены `PublicDesignSettings` в `[username]/page.tsx`
- Обновлены интерфейсы в `CustomizationPanel.tsx`
2. **Панель кастомизации** (`CustomizationPanel.tsx`):
- Checkbox для включения/отключения overlay
- Color picker для выбора цвета
- Range slider для настройки прозрачности
- Live preview перекрытия
3. **Публичная страница** (`[username]/page.tsx`):
- Отображение cover overlay поверх обложки пользователя
## Как протестировать
### 1. Доступ к панели администрирования
```
http://localhost:3000/auth/login
```
### 2. Настройка Cover Overlay
1. Войдите в систему
2. Перейдите в Dashboard
3. Откройте панель кастомизации (кнопка настроек)
4. Найдите секцию "Перекрытие обложки"
5. Включите checkbox "Включить цветовое перекрытие обложки"
6. Выберите цвет (по умолчанию черный #000000)
7. Настройте прозрачность ползунком (по умолчанию 30%)
8. Проверьте preview внизу секции
9. Сохраните настройки
### 3. Проверка на публичной странице
1. Убедитесь что у пользователя загружена обложка (cover image)
2. Перейдите на публичную страницу: `http://localhost:3000/[username]`
3. Если cover overlay включен, вы увидите цветное перекрытие поверх обложки
### API Endpoints
#### Получение настроек дизайна (приватное)
```
GET http://localhost:8000/api/customization/settings/
Authorization: Bearer <token>
```
#### Обновление настроек дизайна
```
PUT http://localhost:8000/api/customization/settings/
Authorization: Bearer <token>
Content-Type: application/json
{
"cover_overlay_enabled": true,
"cover_overlay_color": "#FF5733",
"cover_overlay_opacity": 0.5
}
```
#### Публичное API для страницы пользователя
```
GET http://localhost:8000/api/public/[username]/
```
Ответ включает поля:
```json
{
"design_settings": {
"cover_overlay_enabled": true,
"cover_overlay_color": "#FF5733",
"cover_overlay_opacity": 0.5
}
}
```
## Возможные проблемы
1. **Overlay не отображается**: Проверьте что `cover_overlay_enabled` true в API
2. **Неправильный цвет**: Убедитесь что цвет в hex формате (#RRGGBB)
3. **Overlay слишком яркий/темный**: Настройте opacity (от 0.0 до 1.0)
## Технические детали
- Cover overlay реализован как абсолютно позиционированный div поверх изображения
- CSS pointer-events: none предотвращает блокировку кликов
- Используется rgba() с opacity для плавности переходов
- Preview в админке показывает шахматный фон для демонстрации прозрачности

68
docs/DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,68 @@
# Переменные окружения
Скопируйте `.env.example` в `.env` и настройте следующие переменные:
## Django настройки
- `DJANGO_SECRET_KEY` - Секретный ключ Django (обязательно изменить в продакшене)
- `DJANGO_DEBUG` - Режим отладки (True/False)
- `DJANGO_ALLOWED_HOSTS` - Разрешенные хосты (разделенные запятыми)
## База данных PostgreSQL
- `DATABASE_ENGINE` - Движок базы данных (django.db.backends.postgresql)
- `DATABASE_NAME` - Название базы данных
- `DATABASE_USER` - Пользователь базы данных
- `DATABASE_PASSWORD` - Пароль базы данных
- `DATABASE_HOST` - Хост базы данных (db для Docker)
- `DATABASE_PORT` - Порт базы данных (5432)
## PostgreSQL настройки для контейнера
- `POSTGRES_DB` - Название БД для создания в контейнере
- `POSTGRES_USER` - Пользователь БД для создания в контейнере
- `POSTGRES_PASSWORD` - Пароль пользователя БД в контейнере
## Frontend настройки
- `NEXT_PUBLIC_API_URL` - URL API для frontend (http://localhost:8000)
## Команды для запуска
### Подготовка
```bash
cp .env.example .env
# Отредактируйте .env файл при необходимости
```
### Запуск всех сервисов
```bash
make up # или docker-compose up -d --build
```
### Применение миграций
```bash
make migrate # или docker-compose exec web python manage.py migrate
```
### Остановка сервисов
```bash
make down # или docker-compose down
```
### Запуск тестов
```bash
make test # или docker-compose exec web pytest --maxfail=1 --disable-warnings -q
```
## Доступ к сервисам
- **Frontend**: http://localhost:3000
- **Backend API**: http://localhost:8000/api/
- **Django Admin**: http://localhost:8000/admin/
- **PostgreSQL**: localhost:5432
## Структура проекта
- `backend/` - Django приложение
- `frontend/linktree-frontend/` - Next.js приложение
- `.env` - Переменные окружения (не включается в git)
- `.env.example` - Пример переменных окружения
- `docker-compose.yml` - Конфигурация Docker Compose
- `Makefile` - Команды для удобного управления

112
docs/FIXES.md Normal file
View File

@@ -0,0 +1,112 @@
# Решение проблем со статикой и API
## Исправленные проблемы
### ✅ Статические файлы Django
**Проблема**: Статические файлы Django REST Framework не загружались (404 ошибки)
**Решение**:
1. Добавлен WhiteNoise middleware в `settings.py`:
```python
MIDDLEWARE = [
"corsheaders.middleware.CorsMiddleware",
'django.middleware.security.SecurityMiddleware',
'whitenoise.middleware.WhiteNoiseMiddleware', # Добавлено
# ... остальные middleware
]
```
2. Настроено хранилище статических файлов:
```python
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'
```
3. Создан `entrypoint.sh` для сборки статики при запуске:
```bash
#!/bin/bash
echo "Collecting static files..."
python3 manage.py collectstatic --noinput --clear
echo "Applying database migrations..."
python3 manage.py migrate --noinput
echo "Starting server..."
exec gunicorn backend.wsgi:application --bind 0.0.0.0:8000
```
4. Обновлен `Dockerfile` для использования entrypoint
### ✅ Автоматические миграции
Теперь миграции применяются автоматически при запуске контейнера
### ⚠️ Frontend API подключение
**Проблема**: Frontend не может подключиться к backend API в Docker среде
**Частичное решение**:
- Обновлена конфигурация Next.js для использования `web:8000` внутри Docker
- API прокси работает с редиректами
## Результат
### Работающие сервисы:
- ✅ **Backend**: http://localhost:8000
- ✅ **Backend API**: http://localhost:8000/api/
- ✅ **Статические файлы**: http://localhost:8000/static/*
- ✅ **Django Admin**: http://localhost:8000/admin/
- ✅ **Frontend**: http://localhost:3000
- ✅ **PostgreSQL**: localhost:5432
### Команды для запуска:
```bash
# Запуск всех сервисов
docker-compose up -d
# Проверка статуса
docker-compose ps
# Просмотр логов
docker-compose logs web
docker-compose logs frontend
# Остановка
docker-compose down
```
### Переменные окружения (в .env):
```env
DJANGO_SECRET_KEY=your-secret-key
DJANGO_DEBUG=True
DJANGO_ALLOWED_HOSTS=127.0.0.1,localhost,0.0.0.0
DATABASE_NAME=links_db
DATABASE_USER=links_user
DATABASE_PASSWORD=links_password
DATABASE_HOST=db
DATABASE_PORT=5432
POSTGRES_DB=links_db
POSTGRES_USER=links_user
POSTGRES_PASSWORD=links_password
NEXT_PUBLIC_API_URL=http://localhost:8000
```
## Проверка работы
### Backend статика:
```bash
curl -I http://localhost:8000/static/rest_framework/css/bootstrap.min.css
# Должен вернуть 200 OK
```
### API endpoints:
```bash
curl -s http://localhost:8000/api/ | jq
# Должен вернуть JSON с endpoints
```
### Frontend:
```bash
curl -I http://localhost:3000
# Должен вернуть 200 OK
```

256
docs/MAKEFILE.md Normal file
View File

@@ -0,0 +1,256 @@
# 🛠️ CatLink Makefile Руководство
Makefile предоставляет набор команд для разработки, сборки и деплоя проекта CatLink.
## 📋 Обзор команд
Для просмотра всех доступных команд используйте:
```bash
make help
```
## 🚀 Быстрый старт
### Первая установка
```bash
make install
```
Устанавливает и запускает проект в первый раз.
### Запуск для разработки
```bash
make dev-bg # Запуск в фоне
make dev # Запуск с выводом логов
```
### Проверка статуса
```bash
make status # Статус всех сервисов
make health # Проверка работоспособности
```
## 🔧 Команды разработки
| Команда | Описание |
|---------|----------|
| `make dev` | Запуск в режиме разработки с логами |
| `make dev-bg` | Запуск в фоне для разработки |
| `make up` | Запуск с пересборкой (legacy) |
| `make down` | Остановка всех сервисов |
| `make stop` | Остановка всех сервисов (alias) |
| `make restart` | Перезапуск всех сервисов |
## 🏗️ Команды сборки
| Команда | Описание |
|---------|----------|
| `make build` | Сборка контейнеров без кеша |
| `make build-prod` | Сборка для продакшена |
| `make rebuild-no-cache` | Полная пересборка без кеша |
| `make update` | Обновление зависимостей и пересборка |
## 🚀 Деплой и продакшен
| Команда | Описание |
|---------|----------|
| `make deploy` | Развертывание в продакшен |
| `make ssl` | Настройка SSL с Let's Encrypt |
| `make ssl-setup` | Создание конфигурации SSL |
| `make ssl-cert` | Получение SSL сертификата |
| `make ssl-host-setup` | Локальная настройка nginx + certbot |
### Пример использования SSL
```bash
# Настройка SSL для домена
make ssl-host-setup DOMAIN=catlinks.kr EMAIL=admin@catlinks.kr
```
## 🗄️ Управление базой данных
| Команда | Описание |
|---------|----------|
| `make migrate` | Выполнить миграции |
| `make makemigrations` | Создать новые миграции |
| `make migrate-full` | makemigrations + migrate + collectstatic |
| `make superuser` | Создать суперпользователя |
| `make create-superuser-noninteractive` | Создать суперпользователя из .env |
## 🔍 Мониторинг и логи
| Команда | Описание |
|---------|----------|
| `make logs` | Просмотр всех логов |
| `make logs-web` | Логи backend |
| `make logs-frontend` | Логи frontend |
| `make monitor` | Мониторинг ресурсов |
| `make status` | Статус сервисов |
| `make health` | Проверка работоспособности |
## 🛠️ Инструменты разработки
| Команда | Описание |
|---------|----------|
| `make shell` | Django shell |
| `make shell-db` | Подключение к базе данных |
| `make test` | Запуск тестов |
| `make lint` | Проверка кода |
| `make format` | Форматирование кода |
## 💾 Бэкап и восстановление
| Команда | Описание |
|---------|----------|
| `make backup` | Создать бэкап базы данных |
| `make restore` | Восстановить из бэкапа |
### Пример использования
```bash
# Создание бэкапа
make backup
# Восстановление (интерактивно выберите файл)
make restore
```
## ⚙️ Автоматизация и помощники
| Команда | Описание |
|---------|----------|
| `make generate-env` | Сгенерировать .env файл интерактивно |
| `make scale` | Масштабирование сервисов |
| `make info` | Информация о проекте |
### Генерация .env файла
```bash
make generate-env
```
Интерактивно создает `.env` файл из `.env.example`.
## 🧹 Очистка
| Команда | Описание |
|---------|----------|
| `make clean` | Очистка системы Docker |
| `make clean-all` | ⚠️ Полная очистка (удаляет ВСЕ данные) |
| `make reset` | ⚠️ Сброс к заводским настройкам |
> ⚠️ **Внимание**: Команды `clean-all` и `reset` удаляют все данные безвозвратно!
## 📊 Полезные URL-адреса
После запуска доступны:
- **Frontend**: http://localhost:3000
- **Backend API**: http://localhost:8000
- **Django Admin**: http://localhost:8000/admin
## 💡 Примеры использования
### Стандартный workflow разработки
```bash
# Первый запуск
make install
# Ежедневная разработка
make dev-bg
make logs-web # Просмотр логов при необходимости
# Обновление зависимостей
make update
# Работа с базой данных
make migrate-full
make superuser
# Проверка статуса
make health
```
### Подготовка к продакшену
```bash
# Финальная сборка
make build-prod
# Деплой
make deploy
# Настройка SSL
make ssl-setup
make ssl-cert
```
### Отладка проблем
```bash
# Проверка статуса
make status
make health
# Просмотр логов
make logs
make logs-web
make logs-frontend
# Полная перезагрузка
make restart
# В крайнем случае - полная пересборка
make rebuild-no-cache
```
## 🔧 Технические детали
### Требования
- Docker и Docker Compose
- Make (обычно предустановлен в Linux/macOS)
- Bash (для выполнения скриптов)
### Структура скриптов
Makefile использует скрипты из папки `scripts/`:
- `generate_env.sh` - Генерация .env файла
- `create_superuser.sh` - Создание суперпользователя
- `migrate_and_collect.sh` - Миграции и сбор статики
- `rebuild_no_cache.sh` - Пересборка без кеша
- `ssl_setup.sh` - Настройка SSL
### Переменные окружения
Многие команды используют файл `.env`. Создайте его через:
```bash
make generate-env
```
## 🆘 Решение проблем
### Проблема: "Command not found: make"
**Решение**:
```bash
# Ubuntu/Debian
sudo apt install make
# macOS
xcode-select --install
```
### Проблема: "Permission denied"
**Решение**:
```bash
# Дайте права на выполнение скриптов
chmod +x scripts/*.sh
```
### Проблема: Контейнеры не запускаются
**Решение**:
```bash
# Проверьте статус
make status
# Попробуйте полную пересборку
make rebuild-no-cache
# Проверьте логи
make logs
```
## 📚 Дополнительная документация
- [Деплой и развертывание](./DEPLOYMENT.md)
- [Исправления и патчи](./FIXES.md)
- [Тестирование покрытия](./COVER_OVERLAY_TESTING.md)

88
docs/README.md Normal file
View File

@@ -0,0 +1,88 @@
# 📚 Документация CatLink
Добро пожаловать в документацию проекта CatLink! Здесь вы найдете всю необходимую информацию для работы с проектом.
## 📖 Документы
### 🛠️ Для разработчиков
- **[MAKEFILE.md](./MAKEFILE.md)** - Полное руководство по командам Make для разработки и деплоя
- **[DEPLOYMENT.md](./DEPLOYMENT.md)** - Инструкции по развертыванию в продакшене
- **[FIXES.md](./FIXES.md)** - Известные проблемы и их решения
### 🧪 Для тестировщиков
- **[COVER_OVERLAY_TESTING.md](./COVER_OVERLAY_TESTING.md)** - Документация по тестированию покрытия
## 🚀 Быстрые ссылки
### Для начинающих
1. Начните с [README.md](../README.md) в корне проекта
2. Изучите [MAKEFILE.md](./MAKEFILE.md) для понимания команд
3. Следуйте инструкциям в [DEPLOYMENT.md](./DEPLOYMENT.md) для деплоя
### Для опытных разработчиков
- Используйте `make help` для просмотра всех команд
- Проверьте [FIXES.md](./FIXES.md) при возникновении проблем
- Следуйте документации в [DEPLOYMENT.md](./DEPLOYMENT.md) для продакшена
## 🔧 Структура документации
```
docs/
├── README.md # Этот файл - обзор документации
├── MAKEFILE.md # Руководство по командам Make
├── DEPLOYMENT.md # Инструкции по деплою
├── FIXES.md # Исправления и решения проблем
└── COVER_OVERLAY_TESTING.md # Документация по тестированию
```
## 📋 Краткий справочник команд
### Основные команды Make
```bash
make help # Показать все команды
make install # Первая установка
make dev-bg # Запуск для разработки
make status # Проверить статус
make health # Проверить работоспособность
```
### Управление данными
```bash
make migrate-full # Миграции и сбор статики
make backup # Создать бэкап БД
make restore # Восстановить БД
```
### Деплой
```bash
make deploy # Деплой в продакшен
make ssl-setup # Настройка SSL
```
Подробнее см. [MAKEFILE.md](./MAKEFILE.md)
## 🆘 Получить помощь
1. **Проверьте документацию** - Возможно, ответ уже есть в одном из документов
2. **Поищите в Issues** - [GitHub Issues](https://github.com/smartsoltech/links/issues)
3. **Создайте новый Issue** - Если проблема не найдена
## 🤝 Вклад в документацию
Помогите улучшить документацию:
1. Форкните репозиторий
2. Улучшите или добавьте документацию
3. Создайте Pull Request
### Рекомендации по написанию документации:
- Используйте ясный и понятный язык
- Добавляйте примеры кода
- Включайте скриншоты когда это помогает
- Обновляйте документацию при изменении функционала
---
📖 **[Вернуться к главному README](../README.md)**