# SFERA Stand Runbook

## Network API

- API: `http://192.168.200.60:8000`
- Swagger: `http://192.168.200.60:8000/docs`
- Health: `GET /health`
- Summary: `GET /admin/summary`

## Docker

This OS runs inside a VM. Do not install or use a local Docker Engine here.

Use the shared Docker host for Docker/integration stands:

```bash
docker -H ssh://test-docker ps
```

Shared host:

- SSH alias: `test-docker` / `docker-test`
- Host: `docker-test.cin.su`
- User: `test`

Integrated SFERA testing must be deployed on `docker-test`, including both backend/server
services and the frontend service. Do not fall back to local Docker Engine for project testing.

## Neo4j

Neo4j runs on `docker-test` as container `sfera-neo4j`.

- Browser: `http://docker-test.cin.su:17474`
- Bolt: `bolt://docker-test.cin.su:17687`
- User: `neo4j`
- Password: `password`

API uses:

```text
NEO4J_URI=bolt://docker-test.cin.su:17687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password
```

## Rust BSL Parser

Build the parser locally:

```bash
cd rust
cargo build -p bsl-parser
```

API indexing consumes the Rust JSON contract automatically when the built parser is found at
`rust\target\debug\bsl-parser.exe`. To force a specific parser binary, set:

```text
SFERA_BSL_PARSER=rust\target\debug\bsl-parser.exe
```

If no parser binary is configured or auto-discovered, `semantic-kernel` uses the built-in Python parser fallback.

## Runtime Adapter / 1C Access

`sfera-runtime-adapter` is a separate container/service. It must stay separate from `sfera-api`.

Modes:

```text
RUNTIME_ADAPTER_MODE=mock
RUNTIME_ADAPTER_MODE=local_1c
RUNTIME_ADAPTER_MODE=remote_worker
```

`mock` is the default Docker mode and does not require a 1C platform inside Linux containers. `local_1c` can normalize EDT/XML/file-tree sources without executing Designer. For `.cf`, `.cfe`, archive, and live infobase sources it first returns a safe `designer_dump_planned` response unless execution is explicitly enabled on a trusted worker.

Platform discovery:

- Set `ONEC_DESIGNER_PATH` when the worker has a known Designer CLI path.
- If it is empty, runtime-adapter tries common install roots such as `C:\Program Files\1cv8\*\bin\1cv8.exe`.
- Set `ONEC_DISABLE_AUTO_DISCOVERY=true` to turn discovery off in tests.
- Check `GET /runtime/platform` for `platform_found`, `designer_path`, `discovered_paths`, capabilities, and diagnostics.

Credentials rule:

- Do not store live 1C credentials in repository files, compose files, docs, fixtures, or logs.
- Use `credentials_ref` such as `runtime://prompt/live-upo` or a real vault reference.
- Runtime dump plans redact password-like keys in connection strings before returning diagnostics.

Useful local checks, without storing secrets:

```powershell
Test-Path "C:\EDT\projects\iFCM-UPO"
Invoke-WebRequest -UseBasicParsing -Uri "http://192.168.200.95/upo/ru_RU/" -TimeoutSec 10
Get-ChildItem "C:\Program Files\1cv8","C:\Program Files (x86)\1cv8" -Recurse -Filter 1cv8.exe -ErrorAction SilentlyContinue
```

## Smoke Flow

```bash
POST /projects/demo/index
POST /projects/{project_id}/incremental/file
POST /projects/demo/graph/neo4j/project
GET  /projects/demo/graph/neo4j/callees/Проведение
GET  /projects/demo/graph/neo4j/writes/Проведение
GET  /projects/{project_id}/objects/impact/{object_name}
GET  /projects/{project_id}/objects/attributes/{object_name}
GET  /projects/{project_id}/objects/schema/{object_name}
GET  /projects/{project_id}/objects/tabular-sections/{object_name}
GET  /projects/{project_id}/objects/tabular-sections/{object_name}/columns
GET  /projects/{project_id}/objects/ui/{object_name}
GET  /projects/{project_id}/graph/neo4j/objects/attributes/{object_name}
GET  /projects/{project_id}/graph/neo4j/objects/schema/{object_name}
GET  /projects/{project_id}/graph/neo4j/objects/tabular-sections/{object_name}
GET  /projects/{project_id}/graph/neo4j/objects/tabular-sections/{object_name}/columns
GET  /projects/{project_id}/graph/neo4j/objects/impact/{object_name}
GET  /projects/{project_id}/graph/neo4j/objects/ui/{object_name}
GET  /projects/{project_id}/access/objects/{object_name}/roles
GET  /projects/{project_id}/access/roles/{role_name}/objects
GET  /projects/{project_id}/jobs/scheduled
GET  /projects/{project_id}/integrations
GET  /projects/{project_id}/graph/neo4j/integrations
GET  /projects/{project_id}/graph/neo4j/integrations/{integration_name}/modules
GET  /projects/{project_id}/graph/neo4j/access/objects/{object_name}/roles
GET  /projects/{project_id}/graph/neo4j/access/roles/{role_name}/objects
POST /knowledge/packs
GET  /knowledge/packs
GET  /projects/{project_id}/knowledge/schema-coverage
GET  /projects/{project_id}/patterns
POST /projects/{project_id}/comments
GET  /projects/{project_id}/comments
GET  /projects/{project_id}/comments/{target_id}
POST /projects/{project_id}/ownership
GET  /projects/{project_id}/ownership
GET  /projects/{project_id}/objects/ownership/{object_name}
POST /projects/{project_id}/privacy/markers
GET  /projects/{project_id}/privacy/markers
GET  /projects/{project_id}/objects/privacy/{object_name}
POST /ai/usage
GET  /ai/usage
GET  /ai/usage/summary
GET  /ai/policy
POST /projects/{project_id}/ai/answer-policy
GET  /projects/{project_id}/review
GET  /projects/{project_id}/report
GET  /graph/neo4j/status
```

## Frontend

Frontend app:

```text
Z:\codex\SFERA\frontend\sfera-web
```

Use the mapped `Z:` drive. It points to `\\nas\MST` and avoids Windows tooling issues with UNC current directories:

```bat
cd /d Z:\codex\SFERA\frontend\sfera-web
npm run dev
```

Always run frontend `npm` commands from the mapped `Z:` drive. Do not use `\\nas\MST\...` as the current directory: Windows `cmd.exe` does not support UNC current directories and falls back to `C:\Windows`, which makes npm scripts fail with missing `package.json`.

Default URL:

```text
http://192.168.200.60:3000
```

Editor direct links:

```text
http://192.168.200.60:3000/editor?project=demo&mode=module
http://192.168.200.60:3000/editor?project=demo&mode=form
http://192.168.200.60:3000/editor?project=demo&mode=events
http://192.168.200.60:3000/editor?project=demo&mode=learning
```

Lightweight frontend smoke check against the running stand:

```bat
cd /d Z:\codex\SFERA\frontend\sfera-web
npm run smoke:editor
```

Browser runtime smoke check against the running stand:

```bat
cd /d Z:\codex\SFERA\frontend\sfera-web
npm run smoke:editor:runtime
```

Project Setup / Import Center runtime smoke check against the running stand:

```bat
cd /d Z:\codex\SFERA\frontend\sfera-web
npm run smoke:project-setup
```

Full editor smoke check:

```bat
cd /d Z:\codex\SFERA\frontend\sfera-web
npm run smoke:editor:all
```

Override the checked frontend URL when needed:

```bat
set SFERA_WEB_URL=http://docker-test.cin.su:3000
npm run smoke:editor:all
```

`smoke:editor` checks server-rendered HTML for the overview and editor modes and retries briefly while a freshly started stand settles. `smoke:editor:runtime` launches the installed Chrome/Edge through `playwright-core`, catches browser runtime errors, verifies Monaco in module mode, opens the Versions tab, clicks a version row, checks full version payload details, and exercises metadata draft preview/apply through the API. `smoke:project-setup` prepares the `default` project through the web API proxy, verifies the new Project Setup / IDE Shell route, and saves a metadata draft to workspace history. Set `SFERA_BROWSER_PATH` if Chrome/Edge is installed in a non-standard location.

Docker health smoke can include the Project Setup browser smoke:

```powershell
.\scripts\smoke-test-docker.ps1 `
  -ApiUrl http://docker-test.cin.su:8000 `
  -WebUrl http://docker-test.cin.su:3000 `
  -Neo4jUrl http://docker-test.cin.su:7474 `
  -QdrantUrl http://docker-test.cin.su:6333 `
  -ObjectStorageUrl http://docker-test.cin.su:9000 `
  -IncludeProjectSetupSmoke
```

The frontend resolves the API endpoint in this order:

1. `SFERA_API_URL`
2. `NEXT_PUBLIC_SFERA_API_URL`
3. the current panel host with API port `8000`

Examples:

```text
http://192.168.200.60:3000       -> http://192.168.200.60:8000
http://docker-test.cin.su:3000   -> http://docker-test.cin.su:8000
http://127.0.0.1:3001            -> http://localhost:8000
```

If the API moves to another address or port, set:

```text
SFERA_API_URL=http://api-host:8080
```

If only the derived API port changes, set:

```text
SFERA_API_PORT=8080
```

Do not use `127.0.0.1:8000` as the panel default, because browsers are normally opened from another computer in the LAN. Full Docker stands should run on `docker-test`; local mode is only for the current API + Next.js development loop without a local Docker Engine.

Browser-side editor actions call the API directly, so API CORS must allow the panel origin. By default the API allows localhost, LAN `192.168.*.*` origins, and `docker-test.cin.su`. Override with `SFERA_CORS_ORIGIN_REGEX` only when the stand moves to a different trusted host pattern.

Expected demo projection:

```text
nodes: 5
edges: 6
```

After a project has been projected once to Neo4j, `POST /projects/{project_id}/incremental/file` automatically applies the SIR delta to that project's Neo4j graph. Check `neo4j_projected` / `neo4j_error` in the response.

Object impact includes 1C role access when XML contains role rights, for example `Role -> Right object="Документ.ЗаказПокупателя"`.

Knowledge packs are stored in `knowledge_packs`; importing a BSP/vendor pack also persists enriched `knowledge` records with `pack:{pack_id}` and `vendor:{vendor}` tags for search and coverage.

Pattern mining is available via `GET /projects/{project_id}/patterns?min_support=2` and reports repeated table reads/writes and repeated routine read/write shapes.

Ownership is stored in `collaboration_ownership` and is scoped by project + target lineage. Project review reports `Missing 1C object owner` for root 1C objects without an assigned owner; project report includes ownership and unowned-object counters.

Privacy markers are stored in `privacy_markers` and are scoped by project + target lineage. Review reports `Unclassified sensitive 1C field` for likely sensitive 1C attributes such as ИНН, паспорт, телефон, email, адрес when no privacy classification exists.

AI usage records are stored in `ai_usage`. Use `GET /ai/usage/summary?project_id=...` for dashboard counters and `GET /ai/policy?user_id=...` before AI actions to show token limits and remaining allowance.

AI answer policy is available via `POST /projects/{project_id}/ai/answer-policy`. It does not generate an answer; it returns `allowed`, blocking reasons, warnings, matching knowledge records, privacy markers, and remaining token budget.