[drive-download] README 070326.docx

Google Docs neutral 2026-04-11 4 чанков ~5 мин чтения

Сущности

Вот полный README для нового чата и репозитория. Включает всё — архитектуру, файлы, настройки, эндпоинты, CSS-дизайн-систему, известные проблемы и процедуры деплоя. 🇰🇿 Моя Конституция (constitution.my) Информационный сервис FAQ/разъяснений о Конституции Казахстана. Stack: FastAPI + PostgreSQL + Nginx + Docker Compose. VPS: srv1380923 → /opt/constitution/app Домен: constitution.my (IP: 62.72.32.112, порт 8080) Файловая структура text /opt/constitution/app/ ├── docker-compose.yml # 3 контейнера: api, db, nginx ├── .env # DB credentials (НЕ в Git!) ├── api/ │ └── main.py # FastAPI backend (Uvicorn) ├── static/ │ ├── style.css # Единый CSS (~1200 строк) │ ├── index.html # Главная (featured feed) │ ├── search.html # Страница поиска (client-side) │ ├── basics.html # Раздел "База" │ ├── glossary.html # Глоссарий (аккордеон) │ └── timeline.html # Таймлайн (интерактив) ├── templates/ │ └── item.html # Jinja2 SSR-шаблон карточки FAQ ├── import_yaml.py # Импорт content.yaml → PostgreSQL ├── content.yaml # Контент (вопросы/ответы, 3 языка) ├── nginx.conf # Nginx reverse proxy config ├── deploy.sh # Скрипт деплоя с health-check ├── backup.sh # Бэкап БД с ротацией └── faq_app_view.sql # SQL view для приложения Docker Compose 3 контейнера: API Endpoints База данных Schema: app Ключевые таблицы: app.faq_sections — разделы (code, title) app.faq_items — вопросы (canonical_slug, section_id, sort_order, is_featured) app.faq_i18n — локализации (item_id, lang, question, short_answer, answer_html, facts_html, what_not_change_html, where_detailed_html, misconceptions_html) Section codes: basics, referendum, changes, timeline, rights, institutions, implementation, myths Языки: ru, kk, en (fallback → ru) FTS конфигурации: ru → russian, kk → simple, en → english CSS Дизайн-система (static/style.css) CSS Variables css --bg: #f4f6fa; --card: #ffffff; --text: #0f172a; --muted: #64748b; --line: #e8ecf1; --accent: #2563eb; --accent-bg: rgba(37,99,235,.06); --warn: #f59e0b; --radius: 14px; --font: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; Ключевые компоненты .wrap — контейнер max-width: 820px, центрирован .topbar-unified — sticky навбар (logo + nav-inline + lang-sw) .card — карточка с border-radius: 14px, тенью, hover-анимацией .myths-card — карточка мифов (border-left: warn, gradient bg) .hero — блок hero на accent-bg .item-layout — 2-column grid для страницы карточки (content + sidebar 180px) .foot — footer (pills навигация, соцсети, копирайт) Footer (.foot) css .foot { margin-top: 40px; padding: 24px 0 20px; background: var(--bg); border-top: 1px solid var(--line); } .foot-inner { max-width: 820px; margin: 0 auto; padding: 0 16px; } .foot-nav a { padding: 5px 12px; border-radius: 999px; background: #eef0f4; font-size: 12px; font-weight: 600; } .foot-social a { width: 34px; height: 34px; border-radius: 10px; background: #eef0f4; } ⚠️ КРИТИЧНО: HTML-структура footer .foot ДОЛЖЕН быть ВНЕ .wrap! Иначе стили не применяются (border-top, full-width background пропадают). xml <div class="wrap">  </div>  <div class="foot"> <div class="foot-inner">...</div> </div> Это уже исправлено в search.html и item.html, но при создании новых страниц — проверять! Item page стили .item-layout — white card с border-radius: 12px, padding: 28px 32px .breadcrumb — 12px, color #aaa .item-content h1 — 22px, 800 weight .item-content .lead — 14px, italic removed, color #888 .toc-box — sticky sidebar TOC (top: 24px) .side-share — share icons (copy, telegram, whatsapp) .md h2 — 16px, 700 weight, color #1a1a1a (без border-left) .md table — bordered, border: 1px solid #e5e7eb, th background #f7f8fa Mobile (max-width: 768px) Topbar: 2 rows (brand+lang / nav pills) Item layout: single column, sidebar hidden .wrap { padding: 0 !important; } Footer: column layout, smaller fonts Статические страницы Главная (/ → static/index.html) Fetch /api/featured?lang=... Grid карточек по секциям Filter bar для секций Hero блок Поиск (/search → static/search.html) Client-side: fetch /api/all?lang=..., фильтрация в JS Debounced input (200ms) Highlight для совпадений Группировка результатов по секциям с emoji: {basics:'📖', referendum:'🗳️', changes:'✏️', timeline:'📅', rights:'⚖️', institutions:'🏛️', implementation:'🔧', myths:'🔥'} Карточка (/p/{slug} → templates/item.html) SSR через Jinja2 Блоки: answer_html, facts_html, what_not_change_html, where_detailed_html, misconceptions_html Sidebar: TOC (scroll-spy) + share icons OG meta tags для шэринга Деплой bash cd /opt/constitution/app git pull --rebase docker-compose up -d --build # Ждём health for i in $(seq 1 30); do curl -sf http://127.0.0.1:8080/health && break sleep 2 done Проверки после деплоя bash curl http://127.0.0.1:8080/health curl -sS "http://127.0.0.1:8080/api/featured?lang=ru" | jq '.items | length' curl -sS "http://127.0.0.1:8080/api/search?q=референдум&lang=ru" | jq '.items | length' curl -sI "http://127.0.0.1:8080/p/what-changes-for-citizens?lang=ru" curl -sI "http://127.0.0.1:8080/sitemap.xml" curl -sI "http://127.0.0.1:8080/share/what-changes-for-citizens.png?lang=ru" Импорт контента bash docker exec -i constitution_db psql -U constitution -d constitution < faq_app_view.sql python3 import_yaml.py # Reads content.yaml, upserts into DB Известные проблемы / TODO Footer стили — .foot должен быть вне .wrap. Исправлено в search.html и item.html. При добавлении новых HTML — проверять структуру. Cache busting — CSS подключается с ?v=timestamp. При обновлении стилей обновлять timestamp: sed -i "s/style\.css?v=[0-9]*/style.css?v=$(date +%s)/" static/*.html templates/*.html CSS размер — ~1200 строк с множеством !important overrides. Накопленный технический долг от итеративной разработки. .env — содержит DB credentials, НЕ должен попадать в Git. Языки Fallback: если нет перевода — показывается ru. © 2025–2026 CCS LAB Этот README содержит всю информацию для продолжения работы в новом чате:[ppl-ai-file-upload.s3.amazonaws] Полная файловая структура Все API endpoints Схема БД CSS дизайн-система с переменными и компонентами Критичное правило про footer вне .wrap Mobile breakpoints Процедуры деплоя и импорта Известные проблемы Контейнер | Образ | Порт | Роль constitution_api | python:3.11 + FastAPI | 8000 (internal) | Backend API + SSR constitution_db | postgres:15 | 5432 (internal) | PostgreSQL constitution_nginx | nginx:alpine | 8080 → 80 | Reverse proxy + static Метод | Путь | Описание GET | /health | Health-check GET | / | → /static/index.html GET | /search | → /static/search.html GET | /api/item/{slug} | JSON карточки FAQ GET | /api/featured?lang=ru | Рекомендуемые вопросы GET | /api/search?q=...&lang=ru&limit=20 | Полнотекстовый поиск GET | /api/all?lang=ru | Все записи (для client-side search) GET | /p/{slug}?lang=ru | SSR-страница (SEO/OG) GET | /sitemap.xml | Динамический sitemap GET | /share/{slug}.png?lang=ru | OG-изображение GET | /robots.txt | Robots Код | Название | FTS Config | Статус Код | Название | FTS Config | Статус ru | Русский | russian | Полный kk | Қазақша | simple | Частичный en | English | english | Частичный