documentation: AI specs, data format docs, Russian README

2026-08-01 21:51:13 +03:00
1 parent 4a1e22d68b
commit 84c8ceb172
@@ -0,0 +1,837 @@
+# Документация по формату статических данных
+
+## Оглавление
+1. [Обзор формата статических данных](#обзор-формата-статических-данных)
+2. [Структура директорий и организация](#структура-директорий-и-организация)
+3. [Модели данных и схемы](#модели-данных-и-схемы)
+4. [Правила маршрутизации файлов](#правила-маршрутизации-файлов)
+5. [Разбор компонентов данных](#разбор-компонентов-данных)
+6. [Инструменты управления данными](#инструменты-управления-данными)
+7. [Процесс обогащения](#процесс-обогащения)
+8. [Рабочий процесс контроля качества](#рабочий-процесс-контроля-качества)
+9. [Распространённые проблемы и решения](#распространённые-проблемы-и-решения)
+10. [Краткий справочник](#краткий-справочник)
+
+---
+
+## Обзор формата статических данных
+
+Ponomar PWA использует систему статических данных на основе JSON, организованную по языкам. Все литургические данные предварительно конвертированы из XML-источников и структурированы для эффективной отдачи и рендеринга на стороне клиента.
+
+### Основные принципы
+- **Организация по языкам**: Каждый язык имеет свою директорию в `static/data/`
+- **Хранение в JSON**: Все данные хранятся в виде JSON-файлов для простого парсинга
+- **Маршрутизация по датам**: Календарные данные организованы по датам юлианского календаря (формата ММ-ДД)
+- **Идентификация по CId**: Канонические идентификаторы (CId) уникально идентифицируют святых и праздники
+- **Маршрутизация по префиксу файлов**: Файлы житий маршрутизируются по префиксу CId (01-12 → файлы месяцев)
+
+### Поддерживаемые языки
+- `en` — английский
+- `cu` — церковнославянский
+- `ru` — русский
+- `el` — греческий (включает `el/mono` для монохорда)
+- `fr` — французский
+- `zh` — китайский (включает `zh/Hans` и `zh/Hant` для упрощённого и традиционного)
+- `shared` — межязыковые ресурсы
+
+---
+
+## Структура директорий и организация
+
+```
+static/data/
+├── en/
+│   ├── menaion-bundle.json          # Отображение дата → CId (авторитетно)
+│   ├── en-menaion-bundle.json       # Переопределения для конкретного языка
+│   ├── lives/                       # Жития святых по месяцам
+│   │   ├── 01.json through 12.json  # Файлы месяцев с CId по префиксу (01XX-12XX)
+│   │   └── misc.json                # CId без месячного префикса
+│   ├── menaion/                     # Ежедневные записи минеи (366 дней)
+│   ├── calendar/                    # Метаданные календаря
+│   └── services/                    # Шаблоны богослужений
+├── cu/                              # Церковнославянский (аналогичная структура)
+├── ru/                              # Русский (жития, богослужения)
+├── el/                              # Греческий (включает mono/)
+├── fr/                              # Французский
+├── zh/                              # Китайский (включает Hans/, Hant/)
+└── shared/                          # Межязыковые ресурсы
+    ├── calendar/                    # Календарь подвижных праздников
+    ├── services/                    # Общие шаблоны богослужений
+    └── lives-index.json            # Индекс поиска CId → чтения Писания
+```
+
+### Типы файлов
+- `*-bundle.json` — файлы отображения календаря
+- `lives/*.json` — пачки (bundles) житий святых
+- `menaion/*.json` — ежедневные записи минеи
+- `services/*.json` — шаблоны и логика богослужений
+- `calendar/*.json` — вычисления календаря и метаданные
+
+---
+
+## Модели данных и схемы
+
+### Запись пачки (bundle entry) (menaion-bundle.json)
+```json
+{
+  "01-01": [
+    { "id": "010101" },
+    { "id": "772426" },
+    { "id": "010102" }
+  ]
+}
+```
+**Структура**: Объект с ключами по дате `ММ-ДД`, содержащий массив записей, каждая из которых содержит только поле `"id"` со значением CId.
+
+### Запись жития (life entry) (lives/*.json)
+```json
+{
+  "772426": {
+    "name": {
+      "nominative": "Прп. Сильвестра Печерского (XII)",
+      "short": "Прп. Сильвестра Печерского"
+    },
+    "life": {
+      "id": "minei-0101-772426",
+      "copyright": "Четьи-Минеи свт. Димитрия Ростовского",
+      "text": "<p>Преподобный отец наш Сильвестр...</p>"
+    }
+  }
+}
+```
+**Структура**: Объект с ключами по CId (строка), каждый содержит:
+- `name` (объект) с падежными вариантами (`nominative`, `short`, `genitive` и т.д.)
+- `life` (объект, необязательный) с полями `id`, `copyright` и `text`
+
+### Запись календаря
+```json
+{
+  "pascha": { "year": 2025, "date": "04-20" },
+  "fixed": [
+    { "date": "01-01", "rank": 5, "celebration": "Circumcision" }
+  ]
+}
+```
+**Структура**: Содержит вычисления подвижных праздников и данные неподвижного календаря.
+
+### Запись шаблона богослужения
+```json
+{
+  "ROYALHOURS": {
+    "0": {
+      "text": "Во имя Отца...",
+      "type": "0"
+    }
+  }
+}
+```
+**Структура**: Иерархическая структура богослужения с текстовыми узлами и условной логикой.
+
+---
+
+## Правила маршрутизации файлов
+
+### Маршрутизация файлов житий
+Пачки (bundles) житий маршрутизируются на основе префикса CId:
+
+| Шаблон CId | Целевой файл | Примеры |
+|-------------|--------------|----------|
+| `01XX-01ZZ` | `01.json` | `010101`, `014567` |
+| `02XX-02ZZ` | `02.json` | `023456`, `027890` |
+| ... | ... | ... |
+| `12XX-12ZZ` | `12.json` | `123456`, `127890` |
+| Прочие CId | `misc.json` | `772426`, `373`, `2396` |
+
+**Примеры:**
+- `010101` → `01.json`
+- `1253` → `12.json`  
+- `772426` → `misc.json`
+- `373` → `misc.json`
+
+### Нейминг файлов пачек
+- Основная пачка: `menaion-bundle.json` (для каждого языка)
+- Переопределения языка: `{lang}-menaion-bundle.json`
+- Маршрутизация по префиксу для пачек отсутствует (один файл на язык)
+
+---
+
+## Разбор компонентов данных
+
+### Пачки минеи (Menaion Bundles)
+**Назначение**: Авторитетное отображение дата → CId для рендеринга календаря
+
+**Структура**: JSON с ключами по дате и массивами CId
+```json
+{
+  "01-01": [{ "id": "010101" }, { "id": "772426" }],
+  "01-02": [{ "id": "010201" }, { "id": "772455" }]
+}
+```
+
+**Покрытие**: 366 дней юлианского календаря × несколько записей на день
+**Размер файла**: ~50-100KB на язык
+**Использование**: Представление календаря определяет, каких святых отображать в каждый день
+
+### Пачки житий (Lives Bundles)
+**Назначение**: Биографии и жития святых для обогащения
+
+**Структура**: JSON с ключами по CId, вариантами имён и необязательным текстом жития
+```json
+{
+  "772426": {
+    "name": {
+      "nominative": "Прп. Сильвестра Печерского (XII)",
+      "short": "Прп. Сильвестра Печерского"
+    },
+    "life": {
+      "id": "minei-0101-772426",
+      "copyright": "Четьи-Минеи свт. Димитрия Ростовского",
+      "text": "<p>Полный текст жития в HTML...</p>"
+    }
+  }
+}
+```
+
+**Покрытие**: 3046 CId всего, 1190 с обогащённым life.text
+**Маршрутизация**: по префиксу (01.json-12.json + misc.json)
+**Использование**: Отображение житий на страницах подробностей о святых
+
+### Данные календаря
+**Назначение**: Вычисления подвижных праздников и метаданные календаря
+
+**Компоненты**:
+- `shared/calendar/triodion.json` — Масленица до Великой седмицы
+- `shared/calendar/pentecostarion.json` — Пасха до всех святых
+- `{lang}/calendar/` — данные календаря для конкретного языка
+
+**Ключевые особенности:**
+- Вычисления Пасхалии
+- Определение дат подвижных праздников
+- Определения постных периодов
+- Метаданные праздников и commemorations
+
+### Шаблоны богослужений
+**Назначение**: Структурированные литургические данные с условной логикой
+
+**Организация:**
+```
+services/
+├── octoecheos/          # Восемь гласов × дни
+├── triodion/            # 37 постных разделов
+├── pentecostarion/      # 50 дней Пасхи
+├── menaion/             # 366 ежедневных записей + 34 праздника
+├── canons/              # Пареклит, Осмогласник, Великий канон
+└── shared/templates/    # Переиспользуемые компоненты богослужений
+```
+
+**Структура**: Иерархический JSON с текстовыми узлами и условными префиксами
+- **P-узлы**: Необязательный контент, который может быть включён
+- **Var/I-узлы**: Логика условного выбора
+- **Обычные узлы**: Обязательный контент, всегда включён
+
+### Метаданные Библии
+**Назначение**: Отображения версий Библии и перикоп чтений
+
+**Структура**: Идентификаторы версий и отображения перикоп для 13 версий Библии
+- Церковнославянский
+- Русский синодальный
+- KJV
+- Брентон (Септуагинта)
+- Вульгата
+- Другие версии
+
+### Правила молитв и команды (Prayer Rules & Commands)
+**Назначение**: Структуры суточного круга и определения правила молитвы
+
+**Компоненты:**
+- **Правила молитвы**: Расписания ежедневных чтений
+- **Команды**: Структуры команд богослужений
+- **Часослов**: Часы, кафисмы, повечерие и т.д.
+
+### Правила поста
+**Назначение**: Определения периодов и исключений поста
+
+**Структура**: JSON с правилами поста, периодами и детальными правилами
+- Предпостные периоды
+- Великий пост
+- Безпостные периоды
+- Рыбные и строгие постные дни
+
+---
+
+## Инструменты управления данными
+
+### Конвейер конвертации (`scripts/convert-*.ts`)
+
+#### Главный скрипт
+**`convert-all.ts`** — Оркестрирует все этапы конвертации
+```bash
+npm run convert
+```
+
+Конвертирует данные XML из источников Java Ponomar в формат JSON.
+
+#### Индивидуальные конвертеры
+
+**`convert-lives.ts`** — Конвертация житий святых из XML в JSON
+- Вход: `ponomar/Ponomar/languages/{lang}/xml/lives/*.xml`
+- Выход: `{lang}/lives/{01.json|misc.json}` пачки
+- Особенности:
+  - Парсинг XML с извлечением атрибутов
+  - Нормализация падежей имён
+  - Извлечение грамматических данных
+  - Извлечение данных богослужений
+  - Извлечение ссылок на Писание
+  - Генерация пачек по месячному префиксу
+
+**`convert-calendar.ts`** — Конвертация метаданных календаря
+- Вход: данные календаря XML
+- Выход: структуры календаря JSON
+- Особенности:
+  - Вычисления подвижных праздников
+  - Отображения неподвижных праздников
+  - Определения периодов
+
+**`convert-services.ts`** — Конвертация шаблонов богослужений
+- Вход: определения богослужений XML
+- Выход: шаблоны богослужений JSON
+- Особенности:
+  - Сохранение иерархической структуры
+  - Извлечение условной логики
+  - Нормализация текстовых узлов
+
+**`convert-bible-meta.ts`** — Извлечение метаданных Библии
+- Вход: метаданные Библии XML
+- Выход: отображения версий и перикоп JSON
+
+**`convert-fasting.ts`** — Конвертация правил поста
+- Вход: определения поста XML
+- Выход: правила и периоды поста JSON
+
+**`convert-commands.ts`** — Конвертация структур команд
+- Вход: определения команд XML
+- Выход: структуры команд JSON
+
+**`convert-service-rules.ts`** — Извлечение правил богослужений
+- Вход: определения правил богослужений XML
+- Выход: правила богослужений JSON
+
+### Инструменты миграции (`scripts/migrate-data.ts`)
+
+**Назначение**: Нормализация формата данных между версиями и языками
+
+**Операции:**
+1. Удаление префиксов `@_` из ключей имён житий (все языки)
+2. Удаление `SId` из записей минеи (сохранение id = CId) (все языки)
+3. Переименование директорий богослужений в нижний регистр (cu, el, fr, zh/Hans, zh/Hant, ru)
+4. Выравнивание структуры Осмогласника (cu, fr, zh/Hans, zh/Hant)
+5. Преобразование `TEXT` → `text` в файлах команд
+6. Перемещение общих богослужений в подкаталог `templates/`
+7. Нормализация регистра ключей имён (Nominative → nominative, Short → short)
+8. Миграция объединённых файлов календаря (triodion.json, pentecostarion.json)
+
+**Использование:**
+```bash
+npm run migrate              # Применение миграций
+npm run migrate:dry          # Предпросмотр изменений
+```
+
+### Набор валидации (`scripts/validate-*.ts`)
+
+#### Главный валидатор
+**`validate-data.ts`** — Комплексная валидация данных
+```bash
+npx tsx scripts/validate-data.ts
+```
+**Валидирует:**
+- Структуру записей житий (обязательные поля)
+- Формат пачек житий (ключи CId, объекты name)
+- Целостность данных календаря
+- Структуру шаблонов богослужений
+- Соответствие формату молитв
+- Структуру узлов команд
+- Записи commemorations
+- Определения правил поста
+
+**Вывод:** Количество файлов, ошибки, предупреждения
+
+#### Специализированные валидаторы
+**`validate-i18n.ts`** — Полнота международной локализации
+```bash
+npx tsx scripts/validate-i18n.ts
+```
+Проверяет покрытие по языкам (en/ru/cu).
+
+**`validate-tabs.ts`** — Согласованность вкладок/шаблонов богослужений
+```bash
+npx tsx scripts/validate-tabs.ts
+```
+Валидирует, что вкладки богослужений соответствуют структурам шаблонов.
+
+**`validate-menaion.ts`** — Валидация данных минеи
+```bash
+npx tsx scripts/validate-menaion.ts
+```
+Валидирует записи минеи против правил календаря.
+
+**`validate-prayer-rule.ts`** — Валидация структуры правила молитвы
+```bash
+npx tsx scripts/validate-prayer-rule.ts
+```
+Валидирует формат и полноту правила молитвы.
+
+**Периодические валидаторы:**
+- `validate-triodion.ts` — Валидация периода Триоди
+- `validate-pentecostarion.ts` — Валидация Пятидесятницы
+- `validate-holy-week.ts` — Валидация Страстной седмицы
+- `validate-great-canon.ts` — Валидация Великого канона
+- `validate-great-compline.ts` — Валидация великого повечерия
+- `validate-libcs.ts` — Валидация содержания библиотеки
+
+### Утилиты (`scripts/tools/`)
+
+**`search-texts.ts`** — Полно-текстовый поиск по файлам данных
+```bash
+npx tsx scripts/tools/search-texts.ts <query> [--lang en] [--type prayers]
+```
+
+**`stats.ts`** — Статистика данных и анализ размеров
+```bash
+npx tsx scripts/tools/stats.ts [--lang en]
+```
+
+Предоставляет количество файлов, размеры и разбивку по категориям.
+
+---
+
+## Процесс обогащения
+
+### Обзор
+Процесс обогащения заполняет пустые поля `life.text` в пачках ru/lives, используя агиографические тексты Четьи-Миней (свт. Димитрия Ростовского).
+
+### Подготовка источника: Импорт Четьи-Миней
+
+**`convert-minei.ts`** — Конвертирует EPUB Четьи-Миней в JSON с ключами по датам
+
+**Структура входа (извлечённый EPUB):**
+```
+extracted-epub/
+├── index_split_000.xhtml through index_split_9999.xhtml
+├── toc.ncx
+└── content.opf
+```
+
+**Процесс:**
+1. Последовательный парсинг дневных файлов
+2. Извлечение заголовков: `h2` для дат (`"Память 1 января"`), `h3` для заголовков глав
+3. Извлечение абзацев: `<p class="paragraph1">` для содержания
+4. Сбор сносок из якорей `<a title="...">`
+5. Добавление сносок в виде блока "Примечания:"
+6. Применение исправлений дат заголовков (например, `calibre_toc_10023` → `01-27`)
+7. Построение выходной структуры: `{ "ММ-ДД": [{ title, html }] }`
+
+**Использование:**
+```bash
+npx tsx scripts/convert-minei.ts <extracted-epub-dir> [output.json]
+```
+
+**Вывод:** `scripts/output/minei.json` (игнорируется в git, ~33МБ)
+
+### Конвейер обогащения
+
+**`enrich-lives.ts`** — Нечёткое сопоставление названий minei с именами CId и заполнение пустых житий
+
+**Входные данные:**
+- `scripts/output/minei.json` — источники житий по дате (ММ-ДД)
+- `static/data/cu/menaion-bundle.json` — Авторитетное отображение дата→CId
+- `static/data/ru/lives/*.json` — целевые пачки для обогащения
+
+**Стратегия сопоставления:**
+1. **Токенизация**: Разбиение названий на токены, фильтрация ROLE_WORDS
+2. **Коэффициент Dice**: Вычисление сходства по наборам токенов
+3. **Классификация статусов**:
+   - `already-filled` — Целевой объект уже имеет `life.text` → пропускается
+   - `auto` — Оценка ≥ 0.6, пустой целевой объект → записывается
+   - `review` — Оценка 0.35–0.6 → требуется ручной обзор
+   - `unmatched` — Оценка < 0.35 или нет кандидатов → без совпадения
+
+**Ручные переопределения:**
+```typescript
+const MANUAL_FIXES: Record<string, string> = {
+  '02-02|сказание о сретении': '373',
+  '03-24|воспоминание о чуде': '822',
+  // 214 записей всего
+}
+```
+Формат ключа: `{дата}|{характерная подстрока}` → CId
+
+**Обработка коллизий:** Несколько источников отображаются на один CId
+- Первый источник: записывает `life.html` напрямую (без заголовка)
+- Последующие источники: добавляют `<p><b>{title}</b></p>{html}`
+
+**Маршрутизация файлов:**
+```typescript
+function bundleFileForCid(cid: string): string {
+  return /^(0[1-9]|1[0-2])\d+/.test(cid) 
+    ? `${cid.substring(0, 2)}.json` 
+    : 'misc.json';
+}
+```
+
+**Использование:**
+```bash
+# Тестовый прогон: только отчёт
+npx tsx scripts/enrich-lives.ts
+
+# Ограничение одним месяцем
+npx tsx scripts/enrich-lives.ts --month 01
+
+# Применение изменений
+npx tsx scripts/enrich-lives.ts --write
+
+# Применение изменений для конкретного месяца
+npx tsx scripts/enrich-lives.ts --write --month 01
+```
+
+**Вывод:** `scripts/output/lives-match-report.json` со статусом совпадения для каждого источника
+
+### Пример рабочего процесса
+
+**Этап 1: Подготовка источника**
+```bash
+npx tsx scripts/convert-minei.ts ~/Downloads/chetyi-minei-epub/
+# Вывод: scripts/output/minei.json
+```
+
+**Этап 2: Тестовый анализ**
+```bash
+npx tsx scripts/enrich-lives.ts
+# Показывает: Auto-applied: 184, needs review: 127, unmatched: 94
+# Обзор: scripts/output/lives-match-report.json
+```
+
+**Этап 3: Ручной обзор и исправления**
+- Анализ записей `review` в отчёте
+- Добавление MANUAL_FIXES для проблемных совпадений
+- Повторный запуск, пока количество `review` не станет приемлемым
+
+**Этап 4: Запись и валидация**
+```bash
+npx tsx scripts/enrich-lives.ts --write
+# Показывает: Wrote 7 updated bundle(s)
+npx tsx scripts/validate-data.ts
+npx tsc --noEmit
+npm run build
+```
+
+**Этап 5: Коммит**
+```bash
+git add scripts/enrich-lives.ts scripts/output/lives-match-report.json static/data/ru/lives/
+git commit -m "enrich 121 more ru lives with Chetyi-Minei texts"
+```
+
+### Контроль качества
+
+**Проверка коллизий:** Проверка много-главных записей на правильность заголовков
+```bash
+python3 -c "
+import json, re
+misc = json.load(open('static/data/ru/lives/misc.json'))
+for cid in ['493', '1674', '257401']:  # Известные цели коллизий
+    text = misc[cid]['life']['text']
+    headings = re.findall(r'<b>([^<]+)</b>', text)
+    print(f'{cid}: {len(headings)} глав - {headings}')
+"
+```
+
+**Отслеживание покрытия:** Мониторинг прогресса обогащения
+```bash
+python3 -c "
+import json, glob, os
+total = has = 0
+for fp in glob.glob('static/data/ru/lives/*.json'):
+    data = json.load(open(fp))
+    for cid, entry in data.items():
+        total += 1
+        if isinstance(entry.get('life'), dict) and entry.get('life', {}).get('text'):
+            has += 1
+print(f'Покрытие: {has}/{total} ({has*100//total}%) житий с текстом')
+"
+```
+
+---
+
+## Рабочий процесс контроля качества
+
+### Чек-лист перед коммитом
+
+1. **Валидация данных**
+```bash
+npx tsx scripts/validate-data.ts
+# Ожидается: "All files valid!" или конкретное количество ошибок
+```
+
+2. **Безопасность типов**
+```bash
+npm run check  # или npx tsc --noEmit
+# Ожидается: Нет ошибок TypeScript
+```
+
+3. **Проверка сборки**
+```bash
+npm run build
+# Ожидается: Успешная сборка с размерами пакетов
+```
+
+4. **Функциональное тестирование**
+```bash
+npm run dev
+# Ручной тест: Представление календаря, страницы подробностей святых, отображение житий
+```
+
+### Непрерывный мониторинг
+
+**Автоматические проверки:**
+- Проверка количества файлов (должно быть 274 файла)
+- Возможность парсинга JSON (все файлы данных)
+- Наличие обязательных полей (nominative, life.text для обогащённых записей)
+- Согласованность CId (один и тот же CId должен иметь одинаковое имя на разных языках)
+
+**Обнаружение проблем:**
+- Повреждённые JSON-файлы → ошибки парсинга в validate-data.ts
+- Отсутствие обязательных полей → предупреждения валидации
+- Несоответствие типов → ошибки TypeScript
+- Ошибки сборки → недопустимые структуры данных
+
+### Решение проблем
+
+**Распространённые ошибки валидации:**
+1. **"Missing nominative"** — Объект name отсутствует именительный падеж
+   - **Решение**: Добавить поле `name.nominative` к затронутым записям
+
+2. **"Failed to parse"** — Повреждённый JSON-файл
+   - **Решение**: Повторно запустить конвертацию или исправить синтаксис JSON
+
+3. **"Rank should be 0-8"** — Недопустимое значение rank
+   - **Решение**: Нормализовать rank в диапазон 0-8
+
+4. **Изменения размеров пакетов сборки** — Неожиданное увеличение размера файла
+   - **Решение**: Проверить на наличие дубликатов или искажённого содержимого
+
+---
+
+## Распространённые проблемы и решения
+
+### Артефакты OCR в текстах Четьи-Миней
+
+**Проблема:** Конвертация Четьи-Миней создаёт проблемы OCR, такие как:
+- Латинские символы в русском тексте (`Taиcии` вместо `Таисии`)
+- Маркеры сносок `[1]` в тексте тела
+- Нестабильная пунктуация `[1]` в названиях
+
+**Решение:**
+- Оставлять артефакты OCR как есть (часть исходного текста)
+- Ручные исправления используют точные подстроки OCR для сопоставления
+- Примеры: `'02-15|onissima, odnogo iz lika'` → `'450'`
+
+### Разрешение омонимов в одну дату
+
+**Проблема:** Несколько святых имеют схожие имена в одну дату
+
+**Примеры:**
+- 03-24: Иаков исповедник (68501) против других записей Иаков
+- 02-22: Варадат против Фалассия (оба отображаются на 493)
+- 09-03: Анфим, Аристион, Василиса в одну дату
+
+**Решение:**
+- Использовать характерные подстроки в MANUAL_FIXES
+- Обеспечить уникальность по дате (проверить с помощью скрипта верификации)
+- Для коллизий: оба источника отображаются на один CId (поведение добавления)
+
+### Нарративы на пересекающихся датах
+
+**Проблема:** Некоторые главы minei являются повествованиями, не привязанными к конкретному празднику
+
+**Примеры:**
+- 02-02: "Сказание о Сретении Господнем" (повествование о сретении)
+- 03-24: "Воспоминание о чуде в Печерском монастыре" (история чуда)
+- 08-28: "Память святой праведной Анны" (пророчица Анна)
+
+**Решение:**
+- Определить соответствующий CId для святого/события
+- Отобразить с MANUAL_FIXES, даже если не в ту же дату (хотя текущий конвейер основан на дате)
+- Для записей без подходящего CId: остаться без совпадения
+
+### Неверные отображения в пачке (bundle)
+
+**Проблема:** Некоторые CId указаны в неправильных календарных датах
+
+**Пример:** 
+- 868 Иаков Боровицкий указан под 05-22, фактический праздник 10-23
+
+**Решение:**
+- Вручную исправить menaion-bundle.json
+- Переместить CId с неверной даты на правильную дату
+- Проверить по источникам календаря и традиции
+
+### Пограничные случаи маршрутизации файлов
+
+**Проблема:** Неоднозначная маршрутизация для CId на границах
+
+**Пограничные случаи:**
+- Префиксы `00` → misc.json (не 00.json)
+- Префиксы `99` → misc.json (не 09.json)
+- Нецифровые CId → misc.json
+
+**Решение:** 
+```typescript
+/^(0[1-9]|1[0-2])\d+/.test(cid) // Совпадает только с 01-12, за которыми следуют цифры
+```
+
+### Отображение много-главных коллизий
+
+**Проблема:** Когда несколько источников добавляются к одному CId, первая глава не имеет заголовка
+
+**Поведение:**
+- Первый источник: записывает `life.html` напрямую (без заголовка)
+- Последующие источники: добавляют `<p><b>{title}</b></p>{html}`
+- Результат: Первая глава без заголовка, другие чётко отмечены
+
+**Приемлемый компромисс:** Соответствует всем одно-главным житиям (которые не имеют заголовка)
+
+---
+
+## Краткий справочник
+
+### Сводка npm-скриптов
+
+```bash
+# Разработка
+npm run dev              # Запуск сервера разработки
+npm run build            # Продуктивная сборка
+npm run preview          # Предпросмотр продуктивной сборки
+
+# Конвертация данных
+npm run convert          # Конвертация всех источников XML в JSON
+npm run migrate          # Нормализация к текущему формату
+npm run migrate:dry      # Предпросмотр изменений миграции
+
+# Валидация
+npm run check            # Проверка типов (tsc --noEmit)
+npx tsx scripts/validate-data.ts       # Главный валидатор
+npx tsx scripts/validate-i18n.ts        # Полнота i18n
+npx tsx scripts/validate-tabs.ts        # Согласованность богослужений
+
+# Инструменты
+npx tsx scripts/tools/search-texts.ts <query>    # Поиск по файлам данных
+npx tsx scripts/tools/stats.ts                 # Статистика данных
+
+# Обогащение
+npx tsx scripts/convert-minei.ts <epub-dir>     # Импорт Четьи-Миней
+npx tsx scripts/enrich-lives.ts                # Тестовый прогон обогащения
+npx tsx scripts/enrich-lives.ts --write         # Применение обогащения
+```
+
+### Расширения файлов
+
+| Расширение | Назначение | Формат |
+|-----------|-------------|--------|
+| `.json` | Все файлы статических данных | JSON |
+| `.text` | Ресурсы простого текста | Простой текст |
+| `.xml` | Исходные данные (не в репо) | XML |
+
+### Стратегия Git
+
+**Отслеживается:** `static/data/` (за исключением выходных файлов)
+**Игнорируется:** 
+- `scripts/output/minei.json` (33МБ, генерируемый)
+- `node_modules/`
+- `dist/`
+
+### Важные пути к файлам
+
+```bash
+# Директории данных
+static/data/cu/menaion-bundle.json          # Авторитет календаря
+static/data/ru/lives/                        # Цель для обогащения
+static/data/shared/services/                 # Общие шаблоны богослужений
+
+# Скрипты
+scripts/enrich-lives.ts                     # Конвейер обогащения
+scripts/convert-minei.ts                    # Импорт minei
+scripts/validate-data.ts                    # Главный валидатор
+
+# Выходные файлы
+scripts/output/minei.json                   # Источник minei (игнорируется в git)
+scripts/output/lives-match-report.json      # Отчёт о совпадениях
+```
+
+### Статистика покрытия
+
+**Текущий статус:**
+- Всего CId: 3046
+- Жития с текстом: 1190 (39%)
+- Пустые жития: 1856 (61%)
+
+**Прогресс обогащения:**
+- Главы Четьи-Миней: 1154 всего
+- Совпавшие: 1127 (auto 64 + already-filled 1063)
+- Без совпадений: 27 (минимум: повествования, нет цели, уже заполнено)
+
+### Классификация статусов
+
+| Статус | Значение | Действие |
+|--------|----------|----------|
+| `auto` | Оценка ≥ 0.6, пустая цель | Автоматически записывается |
+| `already-filled` | Цель уже имеет life.text | Пропускается (избыточно) |
+| `review` | Оценка 0.35–0.6 | Требуется ручной обзор |
+| `unmatched` | Оценка < 0.35 или нет кандидатов | Нет подходящей цели |
+
+### Ключевые константы
+
+**Пути к файлам:**
+```typescript
+const MINEI_PATH = 'scripts/output/minei.json';
+const MENAION_BUNDLE_PATH = 'static/data/cu/menaion-bundle.json';
+const LIVES_DIR = 'static/data/ru/lives';
+const REPORT_PATH = 'scripts/output/lives-match-report.json';
+```
+
+**Пороги сопоставления:**
+```typescript
+const AUTO_THRESHOLD = 0.6;      // Автоматическая запись
+const REVIEW_THRESHOLD = 0.35;   // Ручной обзор
+```
+
+**Строка авторских прав:**
+```typescript
+const COPYRIGHT = 'Четьи-Минеи свт. Димитрия Ростовского';
+```
+
+---
+
+## История версий
+
+- **Первоначальный выпуск** — Полная документация формата данных и процесса обогащения
+- **Обновлено** — Добавлен раздел о неверных отображениях пачки, обработка повествований на пересекающихся датах, рабочий процесс QA
+
+---
+
+## Вклад
+
+При вкладе в формат данных или конвейер обогащения:
+
+1. **Тщательно тестируйте:** Запускайте валидацию, проверку типов и сборку перед коммитом
+2. **Документируйте изменения:** Обновляйте эту документацию при любых изменениях схемы
+3. **Сохраняйте совместимость:** Поддерживайте существующие правила маршрутизации файлов и соглашения об именовании
+4. **Валидируйте данные:** Запускайте `validate-data.ts` и исправляйте любые ошибки
+
+---
+
+## Поддержка
+
+По вопросам или проблемам с форматом статических данных:
+- Ознакомьтесь с этой документацией
+- Проверьте существующие проблемы в репозитории
+- Запустите инструменты валидации для диагностики ошибок
+- Изучите конвейер обогащения для проблем сопоставления