NODEDC_1C/docs/HARD_SEMANTIC/refresh_strategy.md

Refresh Strategy (Layer 3)

Date: 2026-03-23
Status: MVP implementation available (canonical_layer/refresh.py)

1. Goal

Provide controlled extraction from 1C into canonical store with reproducible runs, checkpoints, and operational audit trail.

2. Refresh modes

Historical

• bootstrap population of canonical store
• wide scan of selected entity sets
• used to build initial baseline

Incremental

• regular updates for open periods
• optional date window (date_from, date_to)
• preferred default daily mode

Targeted

• selective refresh for one account/document/counterparty context
• optional target_id text filter
• used for point recovery and drill-down gaps

3. Runtime behavior

1. Resolve entity sets (explicit list or keyword-based discovery).
2. Read records from 1C OData per entity set (bounded by limit_per_set).
3. Apply optional date and targeted filters.
4. Map rows to canonical entities and links.
5. Upsert entities/links to canonical store.
6. Update checkpoints for successful sets.
7. Persist run status and metrics into refresh_runs.

4. Run statuses

• success: all requested sets processed
• partial_success: at least one set processed, at least one failed
• failed: no sets processed successfully

5. Execution interfaces

CLI:

• python scripts/run_refresh.py --mode incremental ...

PowerShell wrapper:

• scripts/run_refresh.ps1

API:

• POST /refresh/run
• GET /refresh/runs
• GET /store/stats

6. Safety constraints

• Read-only integration policy stays unchanged.
• No write-back into 1C.
• Local canonical store is internal analytical cache, not source of truth.