documentation: AI specs, data format docs, Russian README

2026-08-01 21:51:13 +03:00
1 parent 4a1e22d68b
commit 84c8ceb172
@@ -0,0 +1,101 @@
+# Ponomar — Православный календарь PWA
+
+Прогрессивное веб-приложение для православного церковного календаря, богослужебных текстов и чтений Писания.
+
+Произведено из оригинального Java-приложения Ponomar от Александра Андреева, Юрия Шардта и Сергея Ф.
+
+**Демо:** <https://ponomar.atroshin.ru>
+
+## Возможности
+
+- **Calendar** — Просмотр сеток месяцев с литургическими днями, периодами поста, чинами и празднованиями. Поддерживает юлианский календарь с григорианскими эквивалентами.
+- **Service Reader** — Сборка богослужебных текстов (часов, кафизм) из структурированных шаблонов с условной логикой.
+- **Bible Reader** — Чтение Писания на 13 языках (церковнославянский, русский синодальный, KJV, Брентон, Вульгата и др.). Позиция чтения для каждой версии сохраняется между сессиями.
+- **Многоязычный интерфейс** — Английский, русский, церковнославянский (со специальными шрифтами для церковнославянского).
+- **PWA** — Устанавливается на настольные и мобильные устройства.
+- **Навигация** — 3 элемента верхнего уровня (Calendar, Library, Settings) с выпадающим меню Library: Библия, Service (Часослов, Сборник, Молитвенное правило, Каноны и акафисты, Паримии, Пареклит, Ирмологий), Праздники (Минея, Постная Триодь).
+
+## Технологический стек
+
+- [TypeScript](https://www.typescriptlang.org/) — полностью типизированный
+- [Vite](https://vitejs.dev/) — инструмент сборки
+- [Tailwind CSS v4](https://tailwindcss.com/) — CSS с утилитарными классами
+- [fast-xml-parser](https://github.com/NaturalIntelligence/fast-xml-parser) — конвертация устаревшего XML (только ручной режим)
+
+## Начало работы
+
+```bash
+npm install
+npm run dev
+```
+
+Файлы данных в `static/data/` отслеживаются в git. Единственный игнорируемый файл вывода — `scripts/output/minei.json` (33МБ источник Четьи-Миней).
+
+Для повторного создания из XML-источников Java Ponomar запустите:
+
+```bash
+npm run convert           # повторная конвертация всех данных из XML
+npm run migrate           # нормализация к текущему формату
+```
+
+Установите `PONOMAR_JAVA_HOME` для указания на локальный клон репозитория Java Ponomar (по умолчанию `../ponomar`).
+
+```bash
+npm run build    # продуктивная сборка
+npm run preview  # предпросмотр продуктивной сборки
+```
+
+## QA / Валидация
+
+```bash
+npx tsx scripts/validate-data.ts        # Главный валидатор (274 файлов проверено)
+npx tsx scripts/validate-i18n.ts         # Полнота i18n (en/ru/cu)
+npx tsx scripts/validate-tabs.ts         # Согласованность вкладок/шаблонов богослужений
+npx tsx scripts/validate-menaion.ts      # Валидация данных минеи
+npx tsx scripts/validate-prayer-rule.ts  # Валидация структуры правила молитвы
+npx tsx scripts/validate-triodion.ts     # Валидация периода Триоди
+npx tsx scripts/validate-pentecostarion.ts # Валидация Пятидесятницы
+npx tsx scripts/validate-holy-week.ts    # Валидация Страстной седмицы
+npx tsx scripts/validate-great-canon.ts  # Валидация Великого канона
+npx tsx scripts/assembler-test.ts       # Интеграционные тесты сборщика богослужений
+```
+
+## Категории литургических текстов (static/data/shared/services/)
+
+- **Triodion** — 37 разделов (Масленица → Великий пост → Страстная седмица)
+- **Pentecostarion** — 50 дней (Пасха → Все святые)
+- **Menaion (daily)** — 367 ежедневных записей (одна на каждый день юлианского календаря)
+- **Menaion (feasts)** — 34 неподвижных праздника с отдельными богослужениями
+- **Canons** — Пареклит (будние дни, 8 гласов × 6 дней = 48), Осмогласник (воскресенье, 8 гласов), Великий канон
+- **Services** — 78 богослужений с полными данными (Пасха, расслабленный, Сергий, Покров и др.; Var/I-префикс + простые P-узлы varNodes теперь перехватываются)
+- **Horologion / Sbornik / Prayer Rule / Akathists / Parimii / Paraclete / Irmologion** — коллекции суточного круга
+- **Lives** — Жития святых (en/cu/ru, 1190/3046 с обогащённым life.text из Четьи-Миней)
+
+## Структура проекта
+
+```
+src/
+  core/          — Логика предметной области (календарь, пасхалия, сборка богослужений, i18n)
+  ui/            — Компоненты представления (приложение, календарь, библия, богослужения, настройки)
+  main.ts        — Точка входа
+scripts/         — Конвертация данных, миграция, валидация, обогащение и инструменты CLI
+static/
+  data/          — Литургические данные в формате JSON (отслеживаются в git)
+  fonts/         — Шрифты для церковнославянского языка
+  icons/         — Иконки PWA
+```
+
+## Лицензия
+
+Такая же, как у оригинального Java-проекта.
+
+## Документация
+
+- **[DATA_FORMAT.md](DATA_FORMAT.md)** — Комплексная документация формата статических данных на английском языке
+- **[DATA_RUS.md](DATA_RUS.md)** — Полная русская документация формата данных и процесса обогащения
+
+Охватывает:
+- Модели статических данных, правила маршрутизации и разбор компонентов
+- Полный набор инструментов для конвертации, миграции и валидации
+- Конвейер обогащения Четьи-Миней и рабочий процесс контроля качества
+- Краткий справочник по всем доступным npm-скриптам и командам