# MVP PROD ARCH Report #3: Stage 1-7 (AS-IS + Runbook)

Дата фиксации: 2026-03-23  
Проект: NDC 1C analytics bridge  
Контур: локальный стенд Windows + 1С + Miniconda  
Статус: **MVP контур Stage 1-7 поднят, Stage 7 частично (спецификация + API-роуты, без полного orchestration-сервиса в прод-режиме)**

---

## 1. Executive summary

На текущем этапе мы имеем рабочую многоуровневую read-only архитектуру:

`1C Source -> Runtime Bridge -> Refresh/Canonical Store -> Feature/Anomaly -> Risk -> API Layer`

Что подтверждено фактически:

1. Runtime bridge к живой 1С доказан и стабилен в read-only режиме.
2. Три жесткие бухгалтерские проверки закрыты как `PROVEN`.
3. Реализован и протестирован Layer 3/4: refresh + canonical store.
4. Реализован и протестирован Layer 5: feature/anomaly engine.
5. Реализован и протестирован Layer 6: risk engine.
6. По Layer 7 есть orchestration-spec и техническая поверхность API, но полноценный production-orchestrator (планировщик/роутер/политики исполнения) еще в roadmap.

---

## 2. Архитектура на текущем этапе

### 2.1 High-level

```text
1С (source of truth, read-only)
   -> toolkit bridge / OData read
   -> Refresh Engine (historical/incremental/targeted)
   -> Canonical Store (entities + links + checkpoints + run logs)
   -> Feature Engine (derived metrics + anomaly signals)
   -> Risk Engine (domain patterns + global risk score)
   -> FastAPI endpoints for integration with assistant/orchestrator
```

### 2.2 Runtime bridge (live)

Базовая связка:

- Proxy: `onec_mcp_toolkit_proxy` (`http://127.0.0.1:6003`)
- 1С обработка: `MCP_Toolkit.epf` в режиме `Прокси`
- Канал: long polling (`/1c/poll`, `/1c/result`)

Важно:

- Это **live request/response**, не snapshot-реплика.
- Для тяжелой аналитики используется выделенный store-слой, а не прямой проход LLM по всей базе 1С.

---

## 3. Stage-by-stage статус (1-7)

## Stage 1. Runtime bridge + guardrails

Статус: **DONE (MVP)**  
Артефакты:

- `docs/ARCH/2 - architecture_stage_report_2026-03-23.md`
- `docs/toolkit_install_runbook.md`
- `docs/toolkit_smoke_test_report.md`
- `docs/toolkit_semantic_probe_report.md`

Ключевой результат:

- Подтвержден live read-only мост через `1c-mcp-toolkit`.
- Статус принятия: `adopt with restrictions`.

## Stage 2. Canonical schema

Статус: **DONE (MVP)**  
Артефакт:

- `docs/accounting_canonical_schema.md`

Реализация:

- `canonical_entities`
- `canonical_links`
- JSON-атрибуты + нормализованные связи.

## Stage 3. Historical loader

Статус: **DONE (MVP)**  
Артефакт:

- `docs/historical_load_plan.md`

Реализация:

- режим `historical` в `scripts/run_refresh.py`.

## Stage 4. Incremental refresh

Статус: **DONE (MVP)**  
Артефакты:

- `docs/refresh_strategy.md`
- `docs/incremental_refresh_plan.md`

Реализация:

- режимы `incremental`, `targeted`
- таблицы `refresh_runs`, `refresh_checkpoints`
- run-status: `success/partial_success/failed`

## Stage 5. Feature / anomaly engine

Статус: **DONE (MVP)**  
Артефакты:

- `docs/analytics_store_design.md`
- `docs/anomaly_engine_spec.md`

Реализация:

- `feature_runs`
- `feature_metrics`
- `anomaly_signals`
- API: `/features/*`

## Stage 6. Risk engine

Статус: **DONE (MVP)**  
Артефакт:

- `docs/risk_engine_spec.md`

Реализация:

- `risk_runs`
- `risk_patterns`
- domain-level risk patterns
- `global_risk_summary`
- API: `/risk/*`

## Stage 7. Assistant orchestration

Статус: **PARTIAL (spec + API-ready surface)**  
Артефакты:

- `docs/assistant_orchestration_spec.md`
- `docs/security_guardrails_readonly.md`

Состояние:

- спецификация маршрутизации готова;
- runtime endpoints для refresh/features/risk готовы;
- полноценный orchestration-service с scheduler/policy execution — **еще не реализован как отдельный прод-компонент**.

---

## 4. Deliverables check (архитектурный комплект)

На дату 2026-03-23 все 8 целевых deliverables присутствуют в `docs/`:

1. `accounting_canonical_schema.md`
2. `analytics_store_design.md`
3. `refresh_strategy.md`
4. `historical_load_plan.md`
5. `incremental_refresh_plan.md`
6. `anomaly_engine_spec.md`
7. `assistant_orchestration_spec.md`
8. `security_guardrails_readonly.md`

---

## 5. Текущее окружение и зависимости

## 5.1 ОС и инструменты

- Windows (локальный стенд)
- 1С платформа: `8.3.27.1936`
- База: Бухгалтерия предприятия 2.0 (лабораторный контур)
- Python: `3.12.10` (технический интерпретатор машины)
- Miniconda env проекта: `ndc_1c_mvp`
- Miniconda env toolkit proxy: `ndc_1c_toolkit` (для bridge-контура)

## 5.2 Python зависимости проекта

`requirements.txt`:

- `fastapi>=0.116.0`
- `odata1cw>=0.0.4`
- `pydantic>=2.11.0`
- `pytest>=8.3.5`
- `python-dotenv>=1.1.0`
- `requests>=2.32.0`
- `SQLAlchemy>=2.0.38`
- `uvicorn>=0.35.0`

## 5.3 Ключевые env-параметры

Из `.env.example`:

- `CANONICAL_DB_URL=sqlite:///X:/1C/NDC_1C/data/canonical_store.db`
- `REFRESH_DEFAULT_LIMIT_PER_SET=200`
- `FEATURE_BASELINE_WINDOW_HOURS=24`
- `ANOMALY_STALE_REFRESH_THRESHOLD_HOURS=6`
- `FEATURE_ENTITY_SCAN_LIMIT=200000`
- `RISK_MEDIUM_THRESHOLD=0.45`
- `RISK_HIGH_THRESHOLD=0.75`
- `RISK_ANOMALY_SCAN_LIMIT=5000`

---

## 6. Полный запуск системы с нуля (на новой машине)

## 6.1 Bootstrap bridge-контура (1С + proxy)

1. Установить 1С платформу и подготовить тестовую базу (read-only пользователь).
2. Установить Miniconda и Git.
3. Подготовить toolkit и env:

```powershell
git clone https://github.com/ROCTUP/1c-mcp-toolkit X:\1C\NDC_1C\external\1c-mcp-toolkit
& 'C:\Users\<USER>\miniconda3\Scripts\conda.exe' create -y -n ndc_1c_toolkit python=3.11
& 'C:\Users\<USER>\miniconda3\envs\ndc_1c_toolkit\python.exe' -m pip install -r X:\1C\NDC_1C\external\1c-mcp-toolkit\requirements.txt
```

4. Запустить proxy:

```powershell
$env:PORT='6003'
$env:TIMEOUT='180'
$env:ALLOW_DANGEROUS_WITH_APPROVAL='false'
$env:ANONYMIZATION_ENABLED='false'
$env:RESPONSE_FORMAT='json'
$env:LOG_LEVEL='INFO'
& 'C:\Users\<USER>\miniconda3\envs\ndc_1c_toolkit\python.exe' -m onec_mcp_toolkit_proxy
```

5. Проверить health:

```powershell
Invoke-WebRequest http://127.0.0.1:6003/health -UseBasicParsing
```

6. В 1С:Предприятии открыть:

`X:\1C\NDC_1C\external\1c-mcp-toolkit\build\MCP_Toolkit.epf`

7. В форме выставить:

- режим: `Прокси`
- сервер: `http://127.0.0.1:6003`
- channel: `default`
- нажать `Подключиться`

## 6.2 Bootstrap аналитического контура (NDC_1C)

1. Подготовить проектную среду:

```powershell
cd X:\1C\NDC_1C
& 'C:\Users\<USER>\miniconda3\Scripts\conda.exe' create -y -n ndc_1c_mvp python=3.11
& 'C:\Users\<USER>\miniconda3\envs\ndc_1c_mvp\python.exe' -m pip install -r requirements.txt
copy .env.example .env
```

2. Настроить `.env` (минимум: `ONEC_INFOBASE`, `ONEC_USERNAME`, `ONEC_PASSWORD`).

3. Запустить API:

```powershell
& 'C:\Users\<USER>\miniconda3\envs\ndc_1c_mvp\python.exe' -m uvicorn canonical_layer.app:app --host 127.0.0.1 --port 8000 --reload
```

4. Запустить data-pipeline:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\run_refresh.ps1 -Mode incremental
powershell -ExecutionPolicy Bypass -File .\scripts\run_features.ps1 -Strict
powershell -ExecutionPolicy Bypass -File .\scripts\run_risk.ps1 -Strict
```

---

## 7. Операционный runbook (ежедневный цикл)

Старт:

1. Поднять bridge proxy и проверить `/health`.
2. Подключить `MCP_Toolkit.epf` в 1С.
3. Выполнить refresh -> features -> risk.
4. Проверить API/хранилища:
   - `/store/stats`
   - `/features/stats`
   - `/risk/stats`

Стоп:

1. Отключить toolkit в 1С.
2. Закрыть 1С.
3. Остановить proxy/API (Ctrl+C).

---

## 8. Реально полученные результаты (фактические прогоны)

Ниже — выдержки из последних реальных прогонов (`logs/*.json`) на дату отчета.

## 8.1 Refresh (incremental)

Источник: `logs/refresh_last_run.json`

```json
{
  "run_id": "7414d9b93c964b589bb863952a027f5e",
  "mode": "incremental",
  "status": "success",
  "records_read": 4,
  "entities_written": 4,
  "links_written": 10,
  "checkpoints_updated": 2
}
```

## 8.2 Feature engine

Источник: `logs/features_last_run.json`

```json
{
  "run_id": "8c311e26916146579e97e110b2243a34",
  "status": "success",
  "entities_total": 2,
  "metrics_written": 19,
  "anomalies_written": 0
}
```

## 8.3 Risk engine

Источник: `logs/risk_last_run.json`

```json
{
  "run_id": "fbad845fdfd64de8a73e35d4da6274e4",
  "status": "success",
  "patterns_written": 1,
  "global_score": 0.05,
  "risk_patterns": [
    {
      "pattern_key": "global_risk_summary",
      "severity": "low"
    }
  ]
}
```

## 8.4 Текущее состояние SQLite store (факт)

Снимок на момент отчета:

- `canonical_store.db` существует, размер `86016` байт
- `canonical_entities=2`
- `canonical_links=10`
- `refresh_runs=3`
- `refresh_checkpoints=2`
- `feature_runs=3`
- `feature_metrics=61`
- `anomaly_signals=0`
- `risk_runs=1`
- `risk_patterns=1`

## 8.5 Тестовый статус

Фактический запуск:

```text
python -m pytest -q
.......                                                                  [100%]
7 passed in 1.86s
```

---

## 9. API-поверхность на текущем этапе

Реализованные endpoints:

- `GET /health`
- `GET /metadata/entity-sets`
- `GET /documents`
- `GET /documents/{document_id}`
- `GET /postings`
- `GET /counterparties/{counterparty_id}/documents`
- `GET /graph/document/{document_id}`
- `GET /store/stats`
- `GET /refresh/runs`
- `POST /refresh/run`
- `GET /features/stats`
- `GET /features/runs`
- `GET /features/metrics`
- `GET /features/anomalies`
- `POST /features/run`
- `GET /risk/stats`
- `GET /risk/runs`
- `GET /risk/patterns`
- `POST /risk/run`

---

## 10. Ограничения и интерпретация текущих цифр

1. Низкий текущий риск (`global_score=0.05`) и отсутствие аномалий отражают **малый текущий объем данных в store**, а не финальную “безрисковость” компании.
2. Stage 7 закрыт документно и по API-ready поверхности, но production-orchestration (policy engine + scheduler + retry orchestration) еще нужно реализовать отдельным сервисом.
3. SQLite используется как MVP-носитель; для прод-контуров нужен PostgreSQL + миграции + эксплуатационные политики.

---

## 11. Что осталось до “MVP production hardening”

1. Реализовать полноценный orchestration-service (Stage 7 runtime).
2. Добавить планировщик и регламенты (`refresh/features/risk`) с retry и алертингом.
3. Вынести store на PostgreSQL, добавить индексы/миграции.
4. Усилить auth/секреты/сетевые ограничения API.
5. Провести калибровку risk/feature правил на расширенном реальном срезе данных.

---

## 12. Итог

На дату **2026-03-23** архитектурный MVP-контур **Stage 1-7** зафиксирован как:

- Stage 1-6: реализованы и подтверждены фактическими прогонами;
- Stage 7: реализован на уровне спецификации и API-операций, но требует выделенного runtime orchestration для production-ready режима.

Проект технически готов к следующему шагу: **production-hardening + orchestration implementation**.

