283 lines
10 KiB
Markdown
283 lines
10 KiB
Markdown
# 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.
|