Skip to content

development.md

Latest commit

 

History

History
157 lines (115 loc) · 4.66 KB

development.md

File metadata and controls

157 lines (115 loc) · 4.66 KB

Разработка и сопровождение

Запуск полного stack

Из корня репозитория:

docker compose up -d --build

Проверить контейнеры:

docker compose ps

Остановить stack:

docker compose down

Пересобрать после изменений в исходниках:

docker compose up -d --build

Health checks

curl http://localhost:3000/api/healthz
curl http://localhost:8081/health
curl http://localhost:8082/health
curl http://localhost:8083/health
curl http://localhost:8084/health
curl http://localhost:8085/health

Health endpoint orchestrator по умолчанию внутренний. Внутри Docker-сети он отдаёт:

GET /healthz
GET /api/healthz

Swagger/OpenAPI

Для service-level debug используйте Swagger pages:

  • Service A: http://localhost:8081/swagger
  • Service C: http://localhost:8082/swagger
  • Service D: http://localhost:8083/swagger
  • Service E: http://localhost:8084/swagger
  • Service F: http://localhost:8085/swagger

Сам UI API является Express gateway и сейчас не отдаёт отдельную Swagger page.

Frontend и UI API workspace

UI workspace находится здесь:

docker-analyzer-ui/

Скрипты из docker-analyzer-ui/package.json:

pnpm build
pnpm typecheck
pnpm start
pnpm dev:frontend
pnpm dev:api

Package layout:

docker-analyzer-ui/artifacts/docker-analyzer   # React frontend
docker-analyzer-ui/artifacts/api-server        # Express UI API

При локальной разработке вне Docker UI API всё равно должен иметь доступ к backend-сервисам по тем service URLs, которые ожидает gateway.

Backend service layout

Backend-сервисы находятся в services/:

ServiceA-Templates       # .NET templates and CWE catalog
ServiceB-Orchestrator    # Node.js pipeline orchestrator
ServiceC-Readiness       # .NET readiness checks
ServiceD-ScanRaw         # .NET raw scanner
ServiceE-cwe-resolver    # .NET CWE resolver and cache
ServiceF-FinalReport     # .NET final read-only report
Shared.Contracts         # shared .NET helpers

Большинство .NET-сервисов следуют layered layout:

Api
Application
Domain
Infrastructure

Service B использует компактную Node.js-структуру:

src/app.ts
src/index.ts
src/routes/
src/lib/

Типовой debugging workflow

  1. Проверить health endpoint UI.
  2. Проверить Swagger pages сервисов.
  3. Проверить docker compose ps на unhealthy containers.
  4. Сначала смотреть logs UI API и orchestrator.
  5. Если падает scan execution, смотреть Service C readiness и Service D logs.
  6. Если падает CWE mapping, смотреть Service E logs и cache state.
  7. Если report page падает после completed run, смотреть Service F logs и request manifest.

Полезные команды:

docker compose logs -f docker-analyzer-ui
docker compose logs -f docker-analyzer-orchestrator
docker compose logs -f servicec-readiness
docker compose logs -f service-d-scan-raw
docker compose logs -f servicee-cwe-resolver
docker compose logs -f service-f-final-report

Правила request_id

request_id должен быть безопасным для filesystem usage. Shared validator разрешает типовые numeric, UUID-like, ULID-like и slug-like значения, но запрещает whitespace, path separators, .. и слишком длинные identifiers.

Как безопасно добавлять функционал

При расширении проекта сохраняйте текущее разделение ответственности:

  • UI pages and hooks остаются в React package.
  • Browser-facing routes остаются в Express UI API namespace /api.
  • Pipeline sequencing принадлежит orchestrator.
  • Template and CWE catalog logic принадлежит Service A.
  • Readiness logic принадлежит Service C.
  • Raw scan logic принадлежит Service D.
  • CWE enrichment and cache logic принадлежит Service E.
  • Final report aggregation принадлежит Service F.
  • Cross-service filesystem and manifest rules принадлежат Shared.Contracts.

Не стоит обходить UI API из браузера, потому что текущий frontend построен вокруг /api/... routes.