documentation: AI specs, data format docs, Russian README

2026-08-01 21:51:13 +03:00
1 parent 4a1e22d68b
commit 84c8ceb172
@@ -0,0 +1,246 @@
+# Data Model Specification
+
+## CId (Canonical Identifier) System
+
+### Format Rules
+
+CIds are identifiers for saints, feasts, and liturgical elements. They follow these routing rules:
+
+| CId Pattern | Target File | Examples | Notes |
+|-------------|-------------|----------|-------|
+| `01XX-01ZZ` | `01.json` | `010101`, `014567` | January saints |
+| `02XX-02ZZ` | `02.json` | `023456`, `027890` | February saints |
+| ... | ... | ... | ... |
+| `12XX-12ZZ` | `12.json` | `123456`, `127890` | December saints |
+| Other CIds | `misc.json` | `772426`, `373`, `868` | Non-month-prefixed |
+
+### Routing Logic
+```typescript
+function bundleFileForCid(cid: string): string {
+  return /^(0[1-9]|1[0-2])\d+/.test(cid) 
+    ? `${cid.substring(0, 2)}.json` 
+    : 'misc.json';
+}
+```
+
+## Menaion Bundle Structure
+
+### Format Definition
+```json
+{
+  "MM-DD": [
+    { "id": "CId" },
+    { "id": "CId" }
+  ]
+}
+```
+
+**Key Points**:
+- Each date key: "MM-DD" format (Julian calendar)
+- Array of objects with only "id" field
+- CIds correspond to actual commemorations on that date
+- One per language: `menaion-bundle.json`, `{lang}-menaion-bundle.json`
+
+### Example
+```json
+{
+  "01-01": [
+    { "id": "010101" },
+    { "id": "772426" },
+    { "id": "010102" }
+  ]
+}
+```
+
+## Life Entry Structure
+
+### Format Definition
+```json
+{
+  "CId": {
+    "name": {
+      "nominative": "Прп. Сильвестра Печерского (XII)",
+      "short": "Прп. Сильвестра Печерского",
+      "genitive": "Прп. Сильвестра Печерского"
+    },
+    "life": {
+      "id": "minei-0101-772426",
+      "copyright": "Четьи-Минеи свт. Димитрия Ростовского",
+      "text": "<p>Complete life text in HTML...</p>"
+    }
+  }
+}
+```
+
+### Required Fields
+- **`CId`**: String key (the canonical identifier)
+- **`name.nominative`**: Required field (validated by validate-data.ts)
+
+### Optional Fields
+- **`name.short`**: Short name variant
+- **`life.text`**: HTML content (only written when empty)
+- **`life.id`**: Source identifier (e.g., "minei-0101-772426")
+- **`life.copyright`**: Copyright string
+
+## Service Template Structure
+
+### Hierarchical JSON Format
+```json
+{
+  "ROYALHOURS": {
+    "0": {
+      "text": "In the name of the Father...",
+      "type": "0"
+    }
+  },
+  "MATINS": {
+    "kathisma": {
+      "text": "Kathisma content..."
+    }
+  }
+}
+```
+
+### Conditional Logic Markers
+- **P-prefix nodes**: Optional content that may be included
+- **Var/I-prefix nodes**: Conditional selection logic
+- **Plain nodes**: Required content always included
+
+## Chetyi-Minei Source Format
+
+### Format Definition
+```json
+{
+  "MM-DD": [
+    {
+      "title": "Память святого X",
+      "html": "<p>Content paragraphs...</p>"
+    }
+  ]
+}
+```
+
+### Key Characteristics
+- Generated by `convert-mines.ts` from EPUB source
+- Stored in `scripts/output/minei.json` (gitignored, 33MB)
+- Titles and HTML are carefully extracted and parsed
+- Footnotes collected and appended as "Примечания:" blocks
+
+## File Organization Rules
+
+### Lives Files
+- **Location**: `static/data/{lang}/lives/`
+- **Files**:
+  - `01.json` through `12.json` (month-prefixed CIds)
+  - `misc.json` (non-month-prefixed CIds)
+- **Routing**: Based on first two digits of CId
+
+### Menaion Files
+- **Location**: `static/data/{lang}/menaion/`
+- **Files**: `01-01.json` through `12-31.json` (daily entries)
+- **Purpose**: Daily liturgical readings by date
+
+### Service Templates
+- **Location**: `static/data/{lang}/services/`
+- **Shared**: `static/data/shared/services/templates/`
+
+### Calendar Data
+- **Location**: `static/data/{lang}/calendar/` and `static/data/shared/calendar/`
+- **Purpose**: Movable feast calculations and metadata
+
+## Data Invariants
+
+### CId Consistency Rules
+- Same CId must have consistent name across all languages
+- Bundle CIds must have corresponding lives entries
+- CIds that exist in bundle must have lives entries
+- CIds with lives entries must exist in bundle for their date
+
+### File Organization Invariants
+- No month file contains CIds with different month prefix
+- `misc.json` contains all CIds outside the 01-12 prefix range
+- All data files are tracked in `static/data/`
+
+### Content Validation Invariants
+- All lives entries must have `name.nominative` field
+- HTML content in `life.text` must be properly escaped
+- JSON files must be parseable (no syntax errors)
+- File routing must match CId prefixes consistently
+
+## Common Data Mistakes to Avoid
+
+### CId Pattern Errors
+- ⚠️ Don't create CIds with invalid prefixes
+- ⚠️ Don't put CIds in wrong month files
+- ⚠️ Don't create duplicate CIds with different meanings
+
+### JSON Structure Errors
+- ⚠️ Don't omit required fields (`name.nominative`)
+- ⚠️ Don't nest structures incorrectly (service templates)
+- ⚠️ Don't mix CId numbers and strings inconsistently
+- ⚠️ Don't leave trailing commas in JSON
+
+### File Organization Mistakes
+- ⚠️ Don't place month-prefixed CIds in misc.json
+- ⚠️ Don't create inconsistent JSON indentation
+- ⚠️ Don't mix languages in incorrect directories
+
+## Examples
+
+### Valid CId Examples
+- `010101` → `01.json` (January saint)
+- `1253` → `12.json` (December saint)
+- `772426` → `misc.json` (non-prefixed saint)
+
+### Invalid CId Examples
+- `00501` → Should not exist (prefix `00` → misc)
+- `13xxx` → Should not exist (prefix `13` → misc)
+
+### File Routing Examples
+- CId `1253` routes to `12.json`
+- CId `772426` routes to `misc.json`
+- CId `010101` routes to `01.json`
+
+### Bundle Entry Examples
+```json
+{
+  "01-15": [
+    { "id": "010201" },
+    { "id": "772455" }
+  ]
+}
+```
+
+### Life Entry Examples
+```json
+{
+  "772426": {
+    "name": {
+      "nominative": "Прп. Сильвестра Печерского (XII)",
+      "short": "Прп. Сильвестра Печерского"
+    },
+    "life": {
+      "id": "minei-0101-772426",
+      "copyright": "Четьи-Минеи свт. Димитрия Ростовского",
+      "text": "<p>Complete life content...</p>"
+    }
+  }
+}
+```
+
+## Current Project State
+
+### Coverage Statistics
+- Total CIds: 3046
+- Lives with text: 1190 (39% coverage)
+- Empty lives: 1856 (61% remain)
+
+### Data Files
+- Total validated files: 274
+- Main source files: 6 Lives bundle files (misc, 01-12)
+- Service template files: Multiple per language
+
+### Recent Changes
+- Bundle fix: 868 Иаков Боровицký moved from 05-22 to 10-23
+- Enrichment: 64 manual fixes added to enrich-lives.ts
+- Coverage increase: 1009→1190 lives with text (191 new)