add: немного описания
This commit is contained in:
@@ -0,0 +1,57 @@
|
||||
# Бэкенд: Архитектура и модули
|
||||
|
||||
## 1. Django Конфигурация (`etpgrf_site/etpgrf_site/`)
|
||||
- **`settings.py`**:
|
||||
- `DEBUG` и `SECRET_KEY` считываются из переменных окружения.
|
||||
- `ADMIN_URL`: настраиваемый префикс панели администратора (по умолчанию `admin/`).
|
||||
- База данных: SQLite в `data/db-etpgrf.sqlite3` с `timeout: 20` для надежности при конкурентных запросах.
|
||||
- Статика: `STATICFILES_DIRS = [BASE_DIR.parent / 'public' / 'static']`, `STATIC_ROOT = BASE_DIR.parent / 'public' / 'static_collected'`.
|
||||
- Медиа: `MEDIA_ROOT = BASE_DIR.parent / 'media'`, `MEDIA_URL = '/media/'`.
|
||||
- Защита за прокси: в `not DEBUG` активированы `SECURE_PROXY_SSL_HEADER`, `SECURE_SSL_REDIRECT`, `SESSION_COOKIE_SECURE`, `CSRF_COOKIE_SECURE`, `USE_X_FORWARDED_HOST`, `USE_X_FORWARDED_PORT`.
|
||||
- **`urls.py`**:
|
||||
- `/{ADMIN_URL}` -> админка Django.
|
||||
- `/` -> `typograph.urls` (главная страница типографа, API обработки и статистики).
|
||||
- `/blog/` -> `blog.urls` (список постов, детальная страница поста).
|
||||
- `/sitemap.xml` -> карта сайта (`PostSitemap`).
|
||||
- `/<slug:slug>/` -> ловушка для статических страниц (например, `/about/`, `/privacy-policy/`, `/donate/`).
|
||||
|
||||
## 2. Приложение `typograph`
|
||||
Отвечает за взаимодействие с библиотекой типографирования `etpgrf` и сбор агрегированной аналитики.
|
||||
|
||||
### Модели (`typograph/models.py`)
|
||||
- **`DailyStat`**:
|
||||
- Агрегированные посуточные показатели (`date` - уникальная дата).
|
||||
- Метрики активности: `index_views`, `process_requests`, `copy_count`.
|
||||
- Объемы данных: `chars_in`, `chars_out`, `chars_copied`.
|
||||
- Производительность: `total_processing_time_ms`, вычисляемое свойство `avg_processing_time_ms`.
|
||||
- `settings_stats`: JSONField со статистикой популярности опций (языки, кавычки, переносы, висячая пунктуация и т.д.).
|
||||
|
||||
### Представления и Эндпоинты (`typograph/views.py`)
|
||||
- `index` (`/`): главная страница, инкрементирует просмотры `index_views`.
|
||||
- `process_text` (`/process/`, POST):
|
||||
- Принимает текст и параметры типографирования из формы.
|
||||
- Инициализирует `LayoutProcessor`, `Hyphenator`, `Typographer` из пакета `etpgrf`.
|
||||
- Производит замер времени обработки `time.perf_counter()`.
|
||||
- Атомарно обновляет счетчики в `DailyStat`.
|
||||
- Возвращает HTML-фрагмент `typograph/result_fragment.html` и заголовок `X-Processing-Time`.
|
||||
- `track_copy` (`/track-copy/`, POST): фиксирует факт и длину скопированного в буфер текста.
|
||||
- `get_stats_summary` (`/stats-summary/`, GET): возвращает компактный HTMX-фрагмент со статистикой для футера.
|
||||
|
||||
## 3. Приложение `blog`
|
||||
Отвечает за публикации, статьи и произвольные статические страницы.
|
||||
|
||||
### Модели (`blog/models.py`)
|
||||
- **`Post`**:
|
||||
- `post_type`: `B` (Пост блога) или `P` (Страница).
|
||||
- `title`, `slug` (автоматическая транслитерация через `pytils.translit.slugify` с обработкой коллизий).
|
||||
- `is_published`, `published_at`, `updated_at`.
|
||||
- `content` (HTML-разметка), `excerpt` (тизер).
|
||||
- `image` (обложка для превью и Open Graph).
|
||||
- SEO-поля: `seo_title`, `seo_description`, `seo_keywords`.
|
||||
- Метод `get_absolute_url()`: возвращает `/blog/<slug>/` для постов или `/<slug>/` для страниц.
|
||||
|
||||
### Представления (`blog/views.py`)
|
||||
- `post_list` (`/blog/`): список опубликованных статей блога с пагинацией.
|
||||
- `post_detail` (`/blog/<slug>/`): детальная страница поста с Open Graph мета-тегами и разметкой.
|
||||
- `page_detail` (`/<slug>/`): отображение статических страниц.
|
||||
- `sitemaps.py`: генерация `sitemap.xml` по опубликованным записям.
|
||||
@@ -0,0 +1,33 @@
|
||||
# Деплой, окружение и регламент релизов
|
||||
|
||||
## 1. Конфигурация окружения (.env)
|
||||
Обязательные переменные:
|
||||
- `SECRET_KEY`: секретный ключ Django.
|
||||
- `DEBUG`: `True` для локальной разработки, `False` для продакшена.
|
||||
- `ALLOWED_HOSTS`: разрешенные хосты через запятую (например, `typograph.cube2.ru,localhost`).
|
||||
- `CSRF_TRUSTED_ORIGINS`: доверенные URL (например, `https://typograph.cube2.ru,http://localhost:8000`).
|
||||
- `ADMIN_URL`: путь к панели администратора (например, `mysecretadmin/`).
|
||||
|
||||
## 2. Docker и инфраструктура
|
||||
- **`Dockerfile`**: базовый образ `python:3.13-slim`, установка Poetry, сборка зависимостей, запуск через Gunicorn.
|
||||
- **`docker-compose.yml`**: конфигурация для разработки (монтирование исходного кода, базы данных и папок статики/медиа).
|
||||
- **`docker-compose.prod.yml`**: конфигурация для продакшена со связанным сервисом Nginx (`config/nginx/`).
|
||||
|
||||
## 3. Чек-лист выпуска релиза (согласно NOTE.md)
|
||||
Перед созданием релизного тега:
|
||||
1. Протестировать функционал и миграции.
|
||||
2. Внести описание изменений в `CHANGELOG.md`.
|
||||
3. Обновить версии в:
|
||||
- `pyproject.toml` (командой `poetry version patch` или вручную).
|
||||
- `etpgrf_site/__init__.py` (при наличии `__version__`).
|
||||
- `etpgrf_site/typograph/templates/typograph/base.html` (версия библиотеки и версия сайта в футере).
|
||||
4. Закоммитить изменения:
|
||||
```bash
|
||||
git add .
|
||||
git commit -am "Обновление версии для релиза vX.Y.Z"
|
||||
git push origin main
|
||||
```
|
||||
5. Запустить пайплайн сборки и деплоя через Gitea Actions путем простановки тега:
|
||||
```bash
|
||||
git tag vX.Y.Z && git push origin vX.Y.Z
|
||||
```
|
||||
@@ -0,0 +1,34 @@
|
||||
# Фронтенд: Структура и сборка
|
||||
|
||||
## 1. Стек и библиотеки
|
||||
- **HTML / Django Templates:** шаблоны `base.html`, компоненты `typograph/` и `blog/`.
|
||||
- **CSS:** Bootstrap 5, Bootstrap Icons, кастомные стили `public/static/css/etpgrf.css` с поддержкой темной/светлой темы.
|
||||
- **Интерактивность:**
|
||||
- **HTMX:** асинхронные запросы (отправка формы типографирования, динамическое обновление плашки со статистикой без перезагрузки).
|
||||
- **Alpine.js:** управление состоянием клиентских виджетов и раскрывающихся списков опций.
|
||||
- **Редактор текста:** CodeMirror 6.
|
||||
|
||||
## 2. Сборка фронтенда и вендорных библиотек (`frontend-assembly/`)
|
||||
- Каталог `frontend-assembly/` управляет сборкой редактора и подготовкой локальных копий всех сторонних библиотек для автономной работы и CDN-fallback:
|
||||
- `src/editor.js`: инициализация CodeMirror 6, подсветка спецсимволов (` `, `­`, тире, кавычки), интеграция темной/светлой темы.
|
||||
- `copy-vendor.js`: копирование дистрибутивов Bootstrap 5, Bootstrap Icons (включая шрифты), HTMX и Alpine.js из `node_modules` в `public/static/vendor/`.
|
||||
- `package.json`: зависимости `@codemirror/*`, `bootstrap`, `bootstrap-icons`, `htmx.org`, `alpinejs`, `esbuild`.
|
||||
- Команды сборки:
|
||||
- `npm run build`: выполняет `build:codemirror` (сборка `editor.js`) и `build:vendor` (копирование всех библиотек в `static/vendor/`).
|
||||
- `npm run build:codemirror`: компилирует бандл в `public/static/codemirror/editor.js`.
|
||||
- `npm run build:vendor`: экспортирует вендорные CSS/JS/шрифты в `public/static/vendor/`.
|
||||
- `npm run watch`: отслеживание изменений CodeMirror в реальном времени.
|
||||
|
||||
## 3. CDN Fallback стратегия (`base.html`)
|
||||
- Основные библиотеки подключаются из публичных CDN (jsDelivr, unpkg) для быстрой доставки и кэширования в браузерах.
|
||||
- При блокировке или недоступности CDN срабатывает автоматический fallback на локальные статические копии:
|
||||
- **CSS (Bootstrap, Bootstrap Icons):** атрибут `onerror="this.onerror=null;this.href='{% static ... %}';"` на тегах `<link>`.
|
||||
- **JS (HTMX, Bootstrap Bundle):** проверка глобального объекта (`window.htmx`, `window.bootstrap`) и подгрузка локальной копии через `document.write`.
|
||||
- **JS (Alpine.js):** `onerror` динамически подключает локальный deferred-скрипт, а также предусмотрена резервная проверка в `DOMContentLoaded`.
|
||||
|
||||
## 4. Клиентская статика (`public/static/`)
|
||||
- `css/etpgrf.css` — основные стили сайта, оформление типографа и блога.
|
||||
- `js/base.js` — вспомогательные клиентские скрипты (обработка куки-баннера, копирование текста, переключение тем).
|
||||
- `codemirror/` — собранный esm-бандл редактора.
|
||||
- `vendor/` — локальные копии сторонних библиотек (`bootstrap`, `bootstrap-icons`, `htmx`, `alpinejs`).
|
||||
- `svg/` и `img/` — векторные и растровые логотипы для светлой/темной темы и мета-тегов Open Graph.
|
||||
@@ -0,0 +1,51 @@
|
||||
# Архитектурный обзор проекта ETPGRF Site
|
||||
|
||||
## 1. Назначение проекта
|
||||
**ETPGRF Site** — веб-сервис и интерфейс для онлайн-типографирования текстов на базе библиотеки `etpgrf`, а также контентная платформа (блог, справочные и статические страницы, статистика использования).
|
||||
|
||||
## 2. Технологический стек
|
||||
- **Backend:** Python 3.13+, Django 6.0+, Poetry.
|
||||
- **База данных:** SQLite 3 (файл `data/db-etpgrf.sqlite3` с увеличенным таймаутом блокировки).
|
||||
- **Frontend:**
|
||||
- Bootstrap 5 (CSS, сетка, компоненты, иконки bootstrap-icons).
|
||||
- Alpine.js (декларативное состояние на клиенте).
|
||||
- HTMX (динамическая подгрузка фрагментов, отправка форм типографирования, статистика).
|
||||
- CodeMirror 6 (продвинутый редактор текста с подсветкой спецсимволов/сущностей).
|
||||
- Сборщик фронтенда: `esbuild` в каталоге `frontend-assembly/`.
|
||||
- **Инфраструктура & Деплой:**
|
||||
- Docker & Docker Compose (`docker-compose.yml` для разработки, `docker-compose.prod.yml` для продакшена).
|
||||
- Nginx (раздача статики `/static/` и медиа `/media/`, SSL-терминация, обратное проксирование к Gunicorn).
|
||||
- Gunicorn (WSGI-сервер Django).
|
||||
- CI/CD: Gitea Actions (автосборка Docker-образов по тегам `v*` и деплой).
|
||||
|
||||
## 3. Структура директорий
|
||||
```
|
||||
2026-etpgrf-site/
|
||||
├── .github/ # Инструкции для AI и CI
|
||||
│ └── copilot-instructions.md
|
||||
├── _prj_blueprint/ # Быстрый контекст и документация архитектуры
|
||||
├── config/ # Конфигурационные файлы Nginx
|
||||
│ └── nginx/
|
||||
├── data/ # Хранилище базы данных SQLite (db-etpgrf.sqlite3)
|
||||
├── etpgrf_site/ # Исходный код Django
|
||||
│ ├── manage.py
|
||||
│ ├── etpgrf_site/ # Корневой модуль конфигурации (settings, urls, wsgi)
|
||||
│ ├── typograph/ # Приложение типографа (обработка, DailyStat, UI)
|
||||
│ └── blog/ # Приложение блога и статических страниц
|
||||
├── frontend-assembly/ # Node.js окружение сборки CodeMirror 6 (esbuild)
|
||||
├── media/ # Загружаемые медиа-файлы (обложки постов)
|
||||
├── public/ # Статика проекта
|
||||
│ ├── static/ # Исходная статика (css, js, img, svg, codemirror)
|
||||
│ └── static_collected/ # Собранная статика collectstatic
|
||||
├── Dockerfile # Сборка продакшн-образа
|
||||
├── docker-compose.yml # Dev-окружение
|
||||
├── docker-compose.prod.yml # Prod-окружение
|
||||
├── pyproject.toml # Poetry зависимости и метаданные
|
||||
├── NOTE.md # Инструкции по релизам и версионированию
|
||||
└── CHANGELOG.md # История версий
|
||||
```
|
||||
|
||||
## 4. Ссылки на детальные описания
|
||||
- [Бэкенд и логика приложений](backend.md)
|
||||
- [Фронтенд и сборка](frontend.md)
|
||||
- [Деплой, окружение и релизный процесс](deployment.md)
|
||||
Reference in New Issue
Block a user