m/sfera
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
sfera/docs/operations/STAND_RUNBOOK.md
T
m 3b845c8fce Initial SFERA platform baseline
2026-05-16 19:03:49 +03:00

10 KiB
Raw Permalink Blame History

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:

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:

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

Rust BSL Parser

Build the parser locally:

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:

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:

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:

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

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:

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:

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:

http://192.168.200.60:3000

Editor direct links:

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:

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

Browser runtime smoke check against the running stand:

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

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

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

Full editor smoke check:

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

Override the checked frontend URL when needed:

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:

.\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:

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:

SFERA_API_URL=http://api-host:8080

If only the derived API port changes, set:

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:

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.

Reference in New Issue View Git Blame Copy Permalink