서버 연동 계약
Organization Console은 현재 FuturePac 합성 조직을 통해 운영 콘솔 경험을 검증합니다. 다만 UI가 직접 FuturePac seed에 묶이지 않도록, 프론트엔드에는 서버가 나중에 제공할 수 있는 read model 계약이 이미 분리되어 있습니다.
이 계약은 서버 구현이 아닙니다. /server 런타임, 실제 writeback, 운영 데이터 변경은 포함하지 않습니다.
현재 상태
| 항목 | 값 |
|---|---|
| 계약 버전 | 2026-04-30.server-backed-read-model.v6 |
| 기본 소스 | FuturePac fixture simulation |
| 서버형 소스 | validated server read model snapshot |
| 실행 모드 | fixture_simulation 또는 server_dry_run |
| live mutation | 현재 전부 false |
| 목적 | Dashboard, Decision Support, Workflows, Issues, Audit, Knowledge, Ontology 화면이 동일한 tenant-neutral DTO로 렌더링되는지 검증 |
코드 경계
| 파일 | 책임 |
|---|---|
serverBackedContract.ts | Organization Console API resource id, path, safety requirement, data-source method mapping |
serverReadModelSchema.ts | JSON payload shape validation, contract version check, org/resource semantic link validation |
serverReadModelAdapter.ts | validated snapshot을 OrganizationConsoleDataSource로 hydrate |
dataSourceRegistry.ts | fixture source와 server read model source 등록/진단 |
futurePacSeedAdapter.ts | FuturePac seed를 tenant-neutral organization-console DTO로 변환 |
리소스 계약
| 리소스 | 방식 | 경로 | 목적 |
|---|---|---|---|
| Summary | GET | /api/organizations/{org_id}/console/summary | 첫 화면 command center, next action, blocker, evidence metrics |
| Staged actions | GET | /api/organizations/{org_id}/console/staged-actions | 리뷰 큐 목록 |
| Staged action detail | GET | /api/organizations/{org_id}/console/staged-actions/{action_id} | 정책, 근거, 권한, writeback preview가 포함된 action detail |
| Simulate writeback | POST | /api/organizations/{org_id}/console/staged-actions/{action_id}/simulate-writeback | live mutation 없는 simulated writeback preview |
| Submit review | POST | /api/organizations/{org_id}/console/staged-actions/{action_id}/reviews | dry-run receipt preview, idempotency boundary |
| Workflow exceptions | GET | /api/organizations/{org_id}/console/workflow-exceptions | blocked workflow queue |
| Workflow exception detail | GET | /api/organizations/{org_id}/console/workflow-exceptions/{run_id} | SLA, retry attempts, correlations, action history |
| Workflow control preview | POST | /api/organizations/{org_id}/console/workflow-exceptions/{run_id}/control-previews | retry, reassign, escalate, pause, cancel preview |
| Workflow DAG | GET | /api/organizations/{org_id}/console/workflows/dag | workflow topology |
| Workflow runs | GET | /api/organizations/{org_id}/console/workflow-runs | runtime table |
| Audit packet | GET | /api/organizations/{org_id}/console/audit-packets/{packet_id} | evidence package and audit readiness |
| Agent tool control | GET | /api/organizations/{org_id}/console/agent-tool-control | agent lifecycle, tool permissions, data access |
| Agent interaction graph | GET | /api/organizations/{org_id}/console/agents/interaction-graph | dashboard agent interaction graph |
| Evaluation health | GET | /api/organizations/{org_id}/console/evaluation-health | eval gates, trace coverage, version comparison, ROI assumptions |
| Knowledge dossier | GET | /api/organizations/{org_id}/console/knowledge-dossiers/{document_id} | evidence dossier cards, entities, relations, events |
| Trace surface | GET | /api/organizations/{org_id}/console/traces/{surface_id} | cross-surface event timeline |
| Event continuity | GET | /api/organizations/{org_id}/console/events/{event_id}/continuity | selected event 이전/현재/다음 context |
| Ontology graph | GET | /api/organizations/{org_id}/console/ontology/graph | ontology graph nodes, edges, clusters |
안전 조건
현재 계약에서 action 성격의 resource는 모두 simulation 또는 preview입니다.
- 서버가 actor identity, org/session scope, policy gate result, evidence refs, tool permission refs, audit preview 또는 receipt, explicit execution mode를 확인하기 전에는 live mutation을 허용하지 않습니다.
simulateWriteback,submitReview,workflowControlPreview는liveMutation: false상태를 유지해야 합니다.server_dry_runread model은 UI를 실제 서버 payload에 맞춰 검증하기 위한 모드이지 운영 시스템 변경 경로가 아닙니다.- FuturePac fixture는 합성 조직 예시입니다. 플랫폼명이나 고객 실적 근거로 사용하지 않습니다.
서버 구현 전 확인할 것
- 생산/프리뷰 console 도메인이 서버 CORS와 demo origin 설정에 반영되어야 합니다.
- OpenAPI 또는 서버 DTO는 위 resource와 동일한 contract version 전략을 가져야 합니다.
- read-only endpoint가 먼저 Dashboard, Decision Support, Workflows, Issues, Audit, Knowledge, Ontology 화면을 렌더링할 수 있어야 합니다.
- action endpoint는 live mode보다 먼저 simulation/dry-run receipt를 지원해야 합니다.
- live mode는 policy, permission, idempotency, adapter patch preview, audit receipt persistence가 모두 준비된 뒤 별도 feature flag로 열어야 합니다.