NODEDC_1C/README.md

# 1C OData MVP Bridge

Read-only MVP bridge between 1C and AI assistant workflows:

1. OData probe (`odata_probe/`)
2. Canonical model and mappers (`canonical_layer/`)
3. FastAPI layer (`canonical_layer/app.py`)
4. Draft MCP configuration (`mcp/`)

## Quick start

```powershell
cd X:\1C\NDC_1C
$Conda = Join-Path $env:USERPROFILE "miniconda3\Scripts\conda.exe"
if (-not (Test-Path $Conda)) { $Conda = Join-Path $env:USERPROFILE "Miniconda3\Scripts\conda.exe" }
& $Conda create -y -n ndc_1c_mvp python=3.11
$EnvPython = Join-Path $env:USERPROFILE "miniconda3\envs\ndc_1c_mvp\python.exe"
if (-not (Test-Path $EnvPython)) { $EnvPython = Join-Path $env:USERPROFILE "Miniconda3\envs\ndc_1c_mvp\python.exe" }
& $EnvPython -m pip install -r requirements.txt
copy .env.example .env
```

Run probe:

```powershell
& $EnvPython -m odata_probe.fetch_metadata
& $EnvPython -m odata_probe.list_entity_sets
& $EnvPython -m odata_probe.probe_entities
& $EnvPython -m odata_probe.dump_sample_links
& $EnvPython scripts/deep_probe_subconto_join.py
& $EnvPython scripts/deep_probe_subconto.py
& $EnvPython scripts/recon_slot3_gap.py
& $EnvPython scripts/deep_probe_accounting_mvp_gate.py
& $EnvPython scripts/check_deeper_access_readiness.py
```

`deep_probe_subconto_join.py` is the regression check for the critical join:
`Document lines (Ref_Key + LineNumber) <-> Accounting register (Recorder + LineNumber)`.
`deep_probe_accounting_mvp_gate.py` runs 3 hard MVP checks and writes a pass/fail verdict.
`recon_slot3_gap.py` focuses on slot `3` evidence quality and writes `logs/slot3_recon_report.json`.
`check_deeper_access_readiness.py` writes `logs/deeper_access_readiness.json` with one snapshot of gate/slot3/tool-artifact readiness.
`scripts/run_probe.ps1` fails intentionally when the MVP gate verdict is not sufficient.

Run FoxyLink endpoint smoke probe:

```powershell
& $EnvPython scripts/foxylink_probe_endpoint.py
& $EnvPython scripts/foxylink_probe_endpoint.py --strict
```

or:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\run_foxylink_probe.ps1
```

`foxylink_probe_endpoint.py` writes `logs/foxylink_probe_report.json` with URL,
status, classification (`reachable`, `auth_failed`, `endpoint_not_found_or_not_published`, etc.),
and response preview.

One-command run:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\run_probe.ps1
```

Run API:

```powershell
& $EnvPython -m uvicorn canonical_layer.app:app --reload --host 127.0.0.1 --port 8000
```

Run canonical refresh (Layer 3 + Layer 4 MVP):

```powershell
& $EnvPython scripts/run_refresh.py --mode historical --limit-per-set 200
& $EnvPython scripts/run_refresh.py --mode incremental --from-date 2026-01-01T00:00:00 --limit-per-set 200
& $EnvPython scripts/run_refresh.py --mode targeted --target-id 68.02 --limit-per-set 200
```

or one-command PowerShell wrapper:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\run_refresh.ps1 -Mode incremental -FromDate 2026-01-01T00:00:00
```

Refresh summary is written to `logs/refresh_last_run.json`.
Canonical store defaults to local sqlite:
`CANONICAL_DB_URL=sqlite:///X:/1C/NDC_1C/data/canonical_store.db`
and can be switched to PostgreSQL with a standard SQLAlchemy URL.

Run feature/anomaly engine (Layer 5 MVP):

```powershell
& $EnvPython scripts/run_features.py --top-account-tokens 20
& $EnvPython scripts/run_features.py --strict
```

PowerShell wrapper:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\run_features.ps1 -Strict
```

Feature summary is written to `logs/features_last_run.json`.
API endpoints for the new layer:

- `POST /features/run`
- `GET /features/stats`
- `GET /features/runs`
- `GET /features/metrics`
- `GET /features/anomalies`

Run risk engine (Layer 6 MVP):

```powershell
& $EnvPython scripts/run_risk.py --strict
```

PowerShell wrapper:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\run_risk.ps1 -Strict
```

Risk summary is written to `logs/risk_last_run.json`.
API endpoints:

- `POST /risk/run`
- `GET /risk/stats`
- `GET /risk/runs`
- `GET /risk/patterns`

Find busiest pre-reporting period and export dense snapshot (for example for 2020):

```powershell
& $EnvPython scripts/run_pre_report_snapshot.py --year 2020 --strict
```

PowerShell wrapper:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\run_pre_report_snapshot.ps1 -Year 2020 -Strict
```

Default scan range:

- start: `2020-01-01T00:00:00Z`
- end (reporting deadline): `2021-03-31T23:59:59Z`

Outputs:

- activity profile: `logs/pre_report_activity_2020.json`
- selected-period snapshot: `logs/pre_report_snapshot_2020_<window>.json`

Run semantic mapper v2 remap on an existing snapshot and compare before/after:

```powershell
& $EnvPython scripts/remap_snapshot_semantic_v2.py
```

Outputs:

- remapped snapshot: `logs/pre_report_snapshot_2020_2020-06_semantic_v2.json`
- metrics delta: `logs/pre_report_snapshot_2020_2020-06_semantic_v2_metrics.json`

Run validation on remapped snapshot:

```powershell
& $EnvPython scripts/run_validation_accounting_analytics.py --snapshot-path logs/pre_report_snapshot_2020_2020-06_semantic_v2.json --output-dir docs/ARCH/validation_run_2026-03-23_semantic_v2 --strict
```

Refresh 2020 export package (ontology, rules, focused samples):

```powershell
& $EnvPython scripts/export_arch_2020_package.py
```

Output directory:

- `docs/ARCH/2020экспорт`

Run router/orchestration fix benchmark profile:

```powershell
& $EnvPython scripts/run_validation_accounting_analytics.py --snapshot-path logs/pre_report_snapshot_2020_2020-06_semantic_v2.json --output-dir docs/ARCH/validation_run_2026-03-23_router_fix --strict
```

Router fix report:

- `docs/ARCH/router_orchestration_fix_report_2026-03-23.md`

## Important

This project is designed for read-only 1C access.
Write operations in OData must remain disabled by 1C roles and by integration policy.