sfera/README.md

# SFERA Platform

**SFERA — Semantic Operating Platform for 1C Ecosystems**

SFERA — enterprise semantic platform для анализа, понимания, индексирования, визуализации и AI-оркестрации экосистем 1С.

SFERA также является современной IDE/authoring-средой для 1С: пользователь должен уметь вручную писать код, создавать и менять объекты, формы, команды и отчёты, а AI должен помогать как pair programmer, который видит текущий код, metadata, связи объектов, доступные переменные и правила платформы.

Платформа строит детерминированное semantic core ядро поверх:
- 1C BSL
- XML metadata
- CF/CFE
- integrations
- access topology
- UI semantics
- scheduled jobs
- object dependencies
- runtime graph

SFERA проектируется как:

```text
Enterprise AI Operating System
for 1C ecosystems
```

---

# Core Philosophy

```text
Semantic truth first.
AI later.
```

AI не является источником истины.

Сначала:
- deterministic parsing
- semantic graph
- metadata topology
- impact analysis
- dependency resolution
- integration discovery
- access analysis

И только потом:
- AI copilots
- AI review
- AI reasoning
- AI onboarding
- AI architecture analysis
- AI migration planning

---

# High-Level Architecture

```text
1C BSL/XML/CF/CFE
        ↓
Rust BSL Parser
        ↓
SIR Snapshot
        ↓
Semantic Kernel
        ↓
Neo4j Semantic Graph
        ↓
Incremental Indexing
        ↓
Impact Analysis
        ↓
AI Operating Layer
```

---

# Main Goals

## Semantic Understanding of 1C

SFERA должна понимать:

- объекты 1С
- формы
- команды
- реквизиты
- табличные части
- роли
- права доступа
- BSL dependencies
- integrations
- scheduled jobs
- runtime topology
- object impact
- UI semantics

---

## 1C IDE and Authoring

SFERA должна давать возможности современной IDE для 1С:

- BSL editor: подсветка, диагностика, folding, outline, go to definition, find references, rename, extract method и безопасные refactoring actions.
- Semantic autocomplete: продолжение кода с учётом текущей процедуры, параметров, локальных переменных, реквизитов объекта, табличных частей, форм, команд, ролей, интеграций и доступных методов 1С.
- AI pair programmer: генерация процедур, функций, запросов, обработчиков команд, движений регистров, проверок заполнения и обработчиков форм.
- Object designer: создание и изменение документов, справочников, регистров, общих модулей, реквизитов, табличных частей, команд и форм.
- Form/report designer: работа с формами, элементами, командами, обработчиками и отчётами в visual/object-oriented интерфейсе.
- Diff/preview/apply: любое AI- или ручное изменение проходит через preview, semantic diff, impact analysis, review и подтверждение.
- Context-aware hints: подсказки не просто по словам, а по текущему объекту 1С, доступным данным, связям, query/write context и runtime/knowledge facts.

AI не ограничивается анализом. Он должен уметь писать код и предлагать структурные изменения, но SFERA обязана показывать последствия и держать контроль применения у пользователя.

---

## Enterprise AI Layer

Поверх semantic graph строится AI operating layer:

- AI code completion
- AI code generation
- AI object/form/report generation
- AI guarded refactoring
- AI code review
- AI impact analysis
- AI onboarding
- AI architecture assistant
- AI dependency explorer
- AI migration assistant
- AI semantic search
- AI documentation generation
- AI risk analysis
- AI integration analysis

AI должен работать поверх semantic truth: перед предложением кода он учитывает текущий BSL-контекст, AST/SIR, metadata object, форму, доступные реквизиты, табличные части, команды, роли, запросы, регистры, интеграции, knowledge records и privacy policy.

---

## 1C Knowledge Coverage

`GET /projects/{project_id}/knowledge/schema-coverage` показывает покрытие knowledge-records для документов, справочников, реквизитов и табличных частей.

`GET /projects/{project_id}/review` добавляет INFO `Missing 1C schema knowledge`, если узел схемы 1С не связан ни с одной knowledge-записью.

`POST /knowledge/packs` импортирует BSP/vendor documentation pack как набор `KnowledgeRecord` с тегами `pack:{pack_id}` и `vendor:{vendor}`. `GET /knowledge/packs` показывает установленные пакеты знаний.

`GET /projects/{project_id}/patterns` выполняет детерминированный pattern mining по SIR: повторяющиеся чтения таблиц, записи таблиц и совпадающие read/write формы процедур.

## 1C Ownership

`POST /projects/{project_id}/comments` добавляет обсуждение к `target_id` внутри проекта, а `GET /projects/{project_id}/comments/{target_id}` возвращает комментарии по конкретному объекту, задаче или lineage.

`POST /projects/{project_id}/ownership` назначает ответственного на 1С-объект по `lineage_id`.

`GET /projects/{project_id}/objects/ownership/{object_name}` возвращает владельцев документа, справочника, регистра, общего модуля и других корневых объектов 1С.

`GET /projects/{project_id}/review` добавляет INFO `Missing 1C object owner` для 1С-объектов без назначенного владельца, а `GET /projects/{project_id}/report` включает `ownership_count`, `unowned_object_count` и `unowned_objects`.

## 1C Privacy

`POST /projects/{project_id}/privacy/markers` назначает privacy-классификацию на `lineage_id`: `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, `PERSONAL_DATA`, `SECRET`.

`GET /projects/{project_id}/objects/privacy/{object_name}` возвращает privacy-маркеры самого 1С-объекта и его прямых реквизитов/табличных частей/форм.

`GET /projects/{project_id}/review` добавляет INFO `Unclassified sensitive 1C field` для реквизитов с чувствительными именами вроде ИНН, паспорт, телефон, email, адрес, если они ещё не классифицированы.

## AI Usage Governance

`POST /ai/usage` записывает факт AI-действия: проект, пользователь, модель, операция, prompt/completion токены и стоимость.

`GET /ai/usage/summary` агрегирует AI usage по проекту, пользователю, модели и операции. `GET /ai/policy` показывает текущий token limit и остаток для пользователя.

`GET /projects/{project_id}/report` включает `ai_usage_request_count`, `ai_usage_total_tokens` и `ai_usage_cost`.

`POST /projects/{project_id}/ai/answer-policy` проверяет, можно ли отвечать на AI-вопрос по выбранному 1С-контексту: учитывает token budget, knowledge records, privacy markers и запрет external model calls.

---

# Monorepo Structure

```text
sfera-platform/

packages/
    bsl-parser-rs/
    sir/
    semantic-kernel/
    neo4j-projection/
    indexing/
    integrations/
    api/
    ai/

frontend/
    sfera-web/

docs/
    architecture/
    frontend/
    operations/
    ai/
    prompts/

.codex/
.cursor/
```

---

# Technology Stack

## Backend

```text
Python
FastAPI
Rust
Neo4j
PostgreSQL
Pydantic
NetworkX
asyncio
uv
```

## Frontend

```text
Next.js
React
TypeScript
Tailwind CSS
shadcn/ui
TanStack Table
TanStack Query
Zustand
Framer Motion
Recharts / ECharts
```

## AI Layer

```text
OpenAI-compatible APIs
Local LLM support
Multi-model routing
AI policy engine
AI audit system
Context orchestration
Token accounting
Semantic AI routing
```

---

# Quick Start

## Environment

```bash
cp .env.example .env
uv sync --all-packages
```

## Run tests

```bash
pytest packages/sir/tests
```

## Run Rust parser

```bash
cargo run -p bsl-parser -- ../tests/golden/english_module.bsl
```

---

# Development Philosophy

SFERA строится как:

```text
Deterministic semantic platform first.
AI-enhanced operating system second.
```

Главный приоритет:
- reproducibility
- deterministic parsing
- semantic correctness
- graph consistency
- auditability
- incremental scalability

---

# Semantic Intermediate Representation (SIR)

Rust parser возвращает deterministic JSON contract:

```json
{
  "procedures": [],
  "calls": [],
  "queries": [],
  "writes": [],
  "diagnostics": []
}
```

SIR является semantic truth snapshot проекта.

---

# Supported 1C Metadata

## Core metadata objects

```text
Catalog
Document
Register
CommonModule
ExchangePlan
ScheduledJob
BusinessProcess
Task
Role
Form
Command
Attribute
TabularSection
Element
```

---

# Semantic Graph Relations

## Main graph relations

```text
CALLS
WRITES
READS
USES_INTEGRATION
HANDLES
CONTAINS
HAS_FORM
HAS_COMMAND
HAS_ATTRIBUTE
HAS_TABULAR_SECTION
HAS_ROLE
HAS_ELEMENT
RUNS
GRANTS_ACCESS
```

---

# Object Impact Analysis

SFERA умеет строить object-level impact:

- реквизиты
- табличные части
- формы
- команды
- BSL handlers
- registers
- integrations
- scheduled jobs
- roles/access
- UI semantics
- cross-module dependencies

---

# Incremental Indexing

SFERA поддерживает incremental semantic updates.

Изменение:
- `.bsl`
- `.xml`
- metadata object
- forms
- handlers

перестраивает только affected semantic graph sections.

---

# Neo4j Projection

Semantic graph может быть выгружен в Neo4j:

```text
SIR Snapshot
    ↓
Neo4j Projection
    ↓
Cypher Queries
    ↓
Graph Analytics
```

---

# Integration Topology

SFERA извлекает integrations из:

- HTTPConnection
- HTTPСоединение
- WSProxy
- FTPConnection
- COMObject
- ExchangePlan
- URL strings
- external services

---

# Scheduled Jobs

Регламентные задания индексируются как runtime semantic graph:

```text
ScheduledJob
    RUNS
Procedure
```

---

# Access Model

Для ролей 1С извлекаются:

- object permissions
- rights
- grants
- access topology

Graph relation:

```text
Role GRANTS_ACCESS Object
```

---

# UI Semantics

SFERA анализирует UI layer:

- forms
- commands
- command handlers
- form elements
- UI actions
- BSL bindings

---

# API Examples

## Object impact

```text
GET /projects/{project_id}/objects/impact/{object_name}
```

## UI semantics

```text
GET /projects/{project_id}/objects/ui/{object_name}
```

## Integrations

```text
GET /projects/{project_id}/integrations
```

## Scheduled jobs

```text
GET /projects/{project_id}/jobs/scheduled
```

## Access graph

```text
GET /projects/{project_id}/access/roles/{role_name}/objects
```

---

# Frontend Philosophy

SFERA UI — не обычная CRM.

Интерфейс должен ощущаться как:

- Linear
- Stripe Dashboard
- Notion
- Attio
- Plane
- Enterprise AI Workspace

---

# Frontend Stack

```text
Next.js
React
TypeScript
Tailwind CSS
shadcn/ui
TanStack Table
Framer Motion
```

---

# Enterprise UI Principles

## Main principles

- clean enterprise minimalism
- dark/light mode
- modular workspace
- AI-native UX
- semantic navigation
- adaptive layouts
- contextual side panels
- command palette
- realtime analytics

---

# AI-Assisted Development

Проект проектируется для работы через:

- Codex
- Cursor
- v0
- AI code review
- AI UI generation
- AI semantic assistants

---

# Codex Workflow

В репозитории присутствуют:

```text
.codex/
.cursor/
docs/design-system.md
docs/component-architecture.md
docs/codex-ui-guidelines.md
prompts/
```

Codex обязан:
- соблюдать architecture rules
- соблюдать design system
- генерировать production-ready TypeScript
- использовать reusable components
- учитывать AI limits/audit/token usage

---

# Frontend Design System

Frontend design system основан на:

```text
Tailwind CSS
shadcn/ui
Radix UI
Design Tokens
Enterprise Layout Rules
```

Основной принцип:

```text
Enterprise AI Operating System
instead of legacy CRM UI
```

---

# AI Operating Layer

Будущие AI возможности:

- AI semantic copilots
- AI impact prediction
- AI migration planning
- AI documentation generation
- AI integration analysis
- AI security review
- AI onboarding assistant
- AI dependency graph reasoning
- AI runtime diagnostics
- AI topology explorer

---

# Infrastructure

Docker Engine локально для development stand не обязателен.

Общий infrastructure host:

```text
docker-test
test-docker
```

Infrastructure documentation:

```text
docs/operations/STAND_RUNBOOK.md
```

---

# First Demo Target

```bsl
Процедура Проведение()
    ПроверитьОстатки();
    Движения.ОстаткиТоваров.Записать();
КонецПроцедуры
```

Expected semantic graph:

```text
Проведение CALLS ПроверитьОстатки
Проведение WRITES РегистрНакопления.ОстаткиТоваров
```

---

# Long-Term Vision

SFERA — это не просто analyzer.

Цель проекта:

```text
Semantic Operating System
for enterprise 1C ecosystems
```

Где:
- semantic graph
- runtime topology
- integrations
- access model
- UI semantics
- AI reasoning
- enterprise workflows
- impact analysis

становятся единой operating platform.

---

# Core Principles

```text
Deterministic.
Semantic.
Incremental.
Observable.
AI-Ready.
Enterprise-Scale.
```

---

# Future Roadmap

## Phase 1

- Rust parser
- SIR
- semantic graph
- Neo4j projection
- incremental indexing

## Phase 2

- semantic APIs
- integrations topology
- access graph
- UI semantics

## Phase 3

- enterprise frontend
- AI copilots
- semantic search
- AI review

## Phase 4

- distributed indexing
- multi-project graph
- semantic federation
- AI orchestration
- autonomous semantic agents