Initial import NDC_1C

docs/canonical_model.md

@@ -0,0 +1,50 @@
+# Canonical Model (MVP)
+
+## Goal
+
+Normalize selected 1C OData entities into a stable internal schema for search, analysis, and assistant workflows.
+
+## Core Entities
+
+- `Organization`
+- `Counterparty`
+- `Contract`
+- `Account`
+- `Subconto`
+- `Document`
+- `Posting`
+- `RegisterMovement`
+- `Period`
+
+## Common Entity Contract
+
+Each canonical entity contains:
+
+- `source_entity`: original OData entity set name
+- `source_id`: stable source identifier (for example `Ref_Key`)
+- `display_name`: best-effort display label
+- `attributes`: source fields from OData row
+- `links`: inferred references to related entities
+
+## Link Semantics
+
+`links[]` represent read-only graph edges inferred from reference-like fields:
+
+- `relation`: currently `reference`
+- `target_entity`: guessed target type by field name
+- `target_id`: ID/GUID of referenced object
+- `source_field`: field that produced the link
+
+## Mapping Rules (v1)
+
+1. Detect `source_id` from `Ref_Key`, `ID`, `Id`, `id`, `Key`.
+2. Detect `display_name` from `Description`, `Presentation`, `Number`, `Code`, and Russian equivalents.
+3. Treat `_Key`, `*Ref*`, and GUID-like values as link candidates.
+4. Classify entity type by entity set name keywords (RU + EN).
+
+## Limitations
+
+- Mapping is heuristic before final per-configuration adapters.
+- Some 1C links may require explicit OData navigation expansion.
+- Date filtering in API is best effort until entity-specific query templates are added.
+