iroum-ax

한국 공공기관 경영평가 보고서 자동화 AI 플랫폼 — KEPCO E&C anchor

한국 공공기관 경영평가 AI 플랫폼 — 안전보건 PoC Walking Skeleton

KEPCO E&C anchor 고객 대상 경영평가 자동화 플랫폼. HWP 문서 수집부터 Gap 추천까지 5개 MVP 기능을 단일 워크플로우로 통과시키는 E2E 슬라이스.

SPEC 참조: .moai/specs/SPEC-AX-001/spec.md

프로젝트 상태

Walking Skeleton + Auth + Observability + ABAC + 증빙 관리 + 평가항목 taxonomy + 점수/리포트/리뷰/루브릭/감사 + 웹 대시보드 완료 (Sprint 0-7 + 16 SPEC GREEN, 2026-05-21)

Python 파이프라인 (SPEC-AX-001 v0.1.2)

192개 단위 테스트 통과 (83% 커버리지)
17개 모듈 (ingestion, mapping, scoring, generation, workers, auth)
5개 AC 그룹 (Document Ingestion, Mapping, Simulation, Generation, Synthesis)

Go Control Plane (SPEC-AX-CTRL-001 v0.1.2)

95개 테스트 (79개 단위 + 11개 통합 + 5개 E2E)
12개 내부 패키지 (workflow, store, audit, scheduler, server, proto, auth)
5개 REQ-CTRL (State Machine, gRPC, REST, PostgreSQL, Celery)

Go 인증 모듈 (SPEC-AX-AUTH-001 v0.1.1)

90개 신규 Go 테스트 + 15개 Python 테스트 = 105 신규 테스트
SF-1 (발행자 검증) + SF-2 (알고리즘 혼동 공격 방어) 통합
OAuth 2.0 BCP (refresh token rotation + family invalidation)
4 E2E PASS + 1 SKIP (REST handler SPEC-AX-AUTH-002 연기)

Go RBAC REST/gRPC Handler (SPEC-AX-AUTH-002 v0.1.2)

34개 신규 테스트 (28 unit + 6 E2E)
default-deny 안전장치 (매핑 미정의 → 503 AUTHZ_MAPPING_MISSING)
체인 순서 강제 (auth → authz → handler)
AUTH-001 SKIP unblock (grep count=0)
plan-auditor PASS 0.92 + evaluator-active CONFIRM 0.8415

Go Server Bootstrap + Dual Listener (SPEC-AX-SERVER-001 v0.1.2)

30개 신규 테스트 (19 unit + 11 E2E/integration)
cmd/server/{main,server,probes}.go — package main 전환 + 11-step 의존성 주입
errgroup dual listener (gRPC :50051 + REST :8080) + graceful shutdown (SIGTERM/SIGINT, 30s timeout)
Health/readiness probes (DB+Redis+JWKS) + audit trail (SERVER_STARTUP/SHUTDOWN)
plan-auditor PASS 0.92 + evaluator-active CONFIRM 0.83

Go 관측성 — Prometheus + OTel (SPEC-AX-OBS-001 v0.1.2)

7개 core collector (HTTP 지연/gRPC 지연/workflow 전이/auth 거부/celery 작업/pg pool/authz 거부)
/metrics endpoint + RBAC (read:metrics 권한, MetricsAuthMiddleware — authn 401 + authz 403 분리)
gRPC UnaryMetricsInterceptor (chain 최외곽, 인증 실패도 계측)
OpenTelemetry tracing skeleton (noop exporter, AlwaysSample — 망분리 정합)
Dependency Inversion (RejectionObserver interface) via internal/auth/observer.go — circular import 영구 해소
24/24 AC GREEN, evaluator-active CONFIRM 89.0 (3 rounds), metrics 87.2% / observability 100%

Go 경량 ABAC (SPEC-AX-AUTH-003 v0.1.0)

RBAC 위에 속성 기반 접근 제어 레이어 추가 (authn → authz → ABAC → handler)
OwnershipCondition (X-Resource-Owner), OrgUnitCondition (iroum-ax-org:), TimeWindowCondition (KST 09:00–18:00)
Admin(RoleAdmin) 전체 우회, 안전 무작동 (fail-safe no-op, REQ-ABAC-009)
외부 의존성 0 (no OPA/Casbin), 망분리 정합, time.LoadLocation 금지
30 AC 검증, abac.go 커버리지 98.5%, evaluator-active PASS 0.905

Go 증빙 관리 (SPEC-AX-EVID-001 v0.1.0)

evidence-core 커버리지 91.4%, 신규 테스트 다수
evidences 테이블 (file_content BYTEA 컬럼) + 마이그레이션 0002_evidence_tables.sql
단일 엔드포인트 POST /api/v1/evidences (생성+버전 통합, SHA-256 단일 패스 스트리밍)
EvidenceBlobStore / dbBlobStore 논리 위치 추상화 (외부 의존 0건, 망분리 정합)
RecordEvidenceCreated / RecordEvidenceVersioned 감사 Recorder 확장
evaluator-active PASS 0.930

Go 평가항목 taxonomy Walking Skeleton (SPEC-AX-EVAL-ITEM-001 v0.1.3)

evaluation_items 테이블: Option A 자기참조 adjacency list (id VARCHAR(64) PK 계층 코드, parent_id self-FK ON DELETE RESTRICT, hierarchy_code UNIQUE) — 단일 테이블, 추가 테이블 없음
EvalItemStore / EvalItemTx 계층 — PgWorkflowStore.pool 단일 pgx 풀 재사용 (신규 연결 없음)
AUD-1 결정적 UUIDv5 audit surrogate: resource_id = uuid.NewSHA1(EvalItemAuditNamespace, []byte(hierarchyCode)) — 실 식별자는 DetailsJSON
EvalItemAuditNamespace = uuid.MustParse("a7f3c2e1-9b4d-5e6f-8a0b-1c2d3e4f5a6b") (@MX:ANCHOR 불변식)
RecordEvalItemCreated / RecordEvalItemUpdated 감사 Recorder 확장 (EVAL_ITEM_CREATED / EVAL_ITEM_UPDATED)
에러 센티널 5종: ErrEvalItemNotFound, ErrEvalItemInvalidInput, ErrEvalItemParentNotFound, ErrEvalItemHierarchyImmutable, ErrEvalItemInvalidStatus
HTTP 엔드포인트 없음 (store/audit 계층 Walking Skeleton 전용); eval_item.go 커버리지 86.2%
evaluator-active PASS (Func 96 / Sec 95 / Craft 82 / Cons 97); plan-auditor PASS 0.955; 22 AC GREEN

Next.js 웹 대시보드 (SPEC-AX-WEB-001 v0.1.0)

5개 데모 화면 + admin 전용 2개 화면 (증빙·평가항목/점수·리포트·리뷰·감사로그·루브릭)
Keycloak 24.x SSO + PKCE/S256 + HttpOnly 쿠키 BFF — XSS 방어, 토큰 자동 갱신
viewer/analyst/admin 3-역할 RBAC UI 가시성 제어 (RoleGate + Edge 미들웨어)
31 REST 엔드포인트 순수 consumer (백엔드 0-diff [HARD])
총 7개 커밋, 82+ 신규 파일 (apps/web/ 신규 워크스페이스)

품질

TRUST 5 PASS (모든 5가지 차원): Tested ✓ | Readable ✓ | Unified ✓ | Secured ✓ | Trackable ✓
16개 SPEC 통합 완료 (AX-001 + CTRL-001 + AUTH-001 + AUTH-002 + SERVER-001 + OBS-001 + AUTH-003 + EVID-001 + EVAL-ITEM-001 + SCORE-001 + SCORE-API-001 + REPORT-001 + REVIEW-001 + RUBRIC-001 + AUDIT-QUERY-001 + WEB-001)

빠른 시작

서버 부팅

# Control Plane 서버 시작 (Go main 진입점)
go run ./apps/control-plane/cmd/server

# 또는 테스트 실행
go test ./apps/control-plane/cmd/server/... -cover

서버 리스너:

gRPC: :50051 (protocol buffers)
REST: :8080 (HTTP/JSON)
Readiness probe: GET /ready (DB + Redis + JWKS 검증)
Liveness probe: GET /health (항상 200)
plan-auditor PASS 0.92 (iter 2), evaluator-active CONFIRM 0.8415 (iter 3)
66개 @MX 태그 (44 ANCHOR + 13 NOTE + 9 WARN)
총 410+ 테스트 (Python 192 + Go 190 + 11 integration + 27 E2E), 55+ 커밋

빠른 시작

# 1. 의존성 설치
make setup

# 2. 로컬 개발 환경 시작 (PostgreSQL + Redis + vLLM)
make dev-up

# 3. Python 파이프라인 테스트 (177개)
python -m pytest tests/unit/ -v

# 4. Go Control Plane 빌드 및 테스트 (95개)
cd apps/control-plane
go build ./cmd/server
go test ./... -v

# 5. 통합 테스트 (E2E: HWP 업로드 → Recommendation)
python -m pytest tests/integration/ -v

빠른 설정

# PostgreSQL DSN (필수 환경변수, 없으면 기본값 사용)
export POSTGRES_DSN="postgres://user:pass@localhost:5432/iroum_ax"

# Redis URL (필수 환경변수)
export REDIS_URL="redis://localhost:6379"

# Go Control Plane 시작
cd apps/control-plane
go run cmd/server/main.go

# gRPC 서버: localhost:50051
# REST API: http://localhost:8080
# 헬스체크: curl http://localhost:8080/healthz

구조 요약

iroum-ax/
├── apps/control-plane/   # Go — 워크플로우 오케스트레이터 (gRPC:50051, REST:8080)
├── apps/web/             # Next.js 14+ — PoC 데모 웹 대시보드 (localhost:3000)
├── pipelines/            # Python — VLM/RAG/Document AI (FastAPI:8000, Celery)
├── schemas/              # Protobuf + OpenAPI 계약 정의
├── deployments/          # Helm Chart + Keycloak realm-export.json
├── tests/                # pytest 통합 테스트 (testcontainers)
└── .moai/specs/          # SPEC 문서 (SPEC-AX-001~WEB-001, 16개 GREEN)

웹 대시보드 (SPEC-AX-WEB-001)

PoC 데모용 Next.js 14+ App Router 웹 대시보드. Go control-plane REST API의 순수 consumer.

데모 화면

화면	경로	허용 역할
로그인	`/login`	전체
증빙 업로드/목록	`/dashboard/evidences`	viewer(읽기) / analyst+admin(업로드)
평가항목 트리 + 점수 입력	`/dashboard/evaluation-items`	viewer(읽기) / analyst+admin(입력)
범주 리포트	`/dashboard/reports/{categoryId}`	전체
리뷰 Kanban 보드	`/dashboard/reviews`	viewer(읽기) / analyst+admin(제출) / admin(승인/반려)
감사 로그	`/dashboard/audit-logs`	admin 전용
루브릭 임계값	`/dashboard/rubric/thresholds`	admin 전용

웹 대시보드 시작

# 1. Go control-plane 실행 (필수 선행)
cd apps/control-plane && go run cmd/server/main.go
# REST API: http://localhost:8080

# 2. Keycloak 실행 (Docker Compose)
docker compose -f deployments/docker-compose.yml up keycloak

# 3. 웹 대시보드 실행
cd apps/web && npm install && npm run dev
# 웹 UI: http://localhost:3000

웹 기술 스택

영역	선택
프레임워크	Next.js 14+ (App Router, React Server Components)
언어	TypeScript 5.4+ (strict mode)
UI 키트	shadcn/ui + Tailwind CSS 3.4+
데이터 패칭	TanStack Query v5
인증	Keycloak 24.x OIDC + PKCE/S256 + HttpOnly 쿠키 BFF
아이콘	lucide-react
테스트	Vitest + React Testing Library

기술 스택

계층	기술
VLM (OCR)	Qwen2-VL 7B
텍스트 LLM	Qwen 2.5 7B (CPU 직접 로딩)
임베딩	ko-sroberta-multitask (768 dim)
Vector DB	PostgreSQL 16 + pgvector (HNSW)
API	FastAPI + gRPC-Gateway v2
비동기 큐	Celery + Redis
오케스트레이터	Go 1.22 + K8s (Helm)

아키텍처 & 설계

모든 주요 설계 결정과 모듈 맵핑은 아래 문서에서 확인하세요:

Architecture Overview: 3계층 아키텍처 (Go Control Plane + Python 파이프라인 + TypeScript UI) · 모노레포 구조 · E2E 데이터 흐름
Go Control Plane: 12개 내부 패키지 · State Machine · gRPC/REST · PostgreSQL Store · Celery Dispatcher · @MX:ANCHOR 분석
Python Pipelines: Python 17개 모듈 · REQ-AX 매핑 · @MX:ANCHOR
Data Models: 공유 모델 · Pydantic 스키마 · 에러 정의 · 로깅 구조
Data Flow: HWP 입력 → Go orchestration → Python 처리 → Recommendation 출력
Requirements Traceability: REQ-CTRL + REQ-AX + REQ-UBI 매트릭스 · AC ↔ 구현 ↔ 테스트 (272개 테스트 총합)

개발 명령어

make lint         # ruff + mypy + go vet
make format       # ruff format + gofmt
make test         # lint → pytest → go test (모든 177개 테스트)
make dev-down     # 로컬 환경 종료
make docker-build # Docker 이미지 빌드

다음 단계 (후속 SPEC)

웹 대시보드 확장

SPEC 후보	범위
SPEC-AX-WEB-002	Playwright e2e 자동화 + WCAG 2.1 AA 접근성 감사
SPEC-AX-WEB-003	WebSocket 실시간 알림 (리뷰 상태 변경 푸시)
SPEC-AX-WEB-004	다국어/i18n (영어 + 일본어)
SPEC-AX-WEB-005	HWP/Excel 임포트 UI
SPEC-AX-OPS-001	Docker 컨테이너화 + CI/CD 파이프라인

플랫폼 확장

Sprint	SPEC 후보	범위
-	SPEC-AX-EXPANDED-001	다중 평가항목 (안전보건 → 500개 전체)
Phase 3	SPEC-AX-{ESG,AUDIT,LICENSE}-001	인접 도메인 확장
Phase 4+	SPEC-AX-FINTECH-001	금융권 규제 보고서 (조건: 공공 anchor 성공 3+ 확보)

아키텍처 결정 기록 (ADR)

주요 설계 결정은 docs/adr/에 영구 보존됩니다.

핵심 ADR:

모든 ADR 목록은 docs/adr/README.md를 참조하세요.

라이선스

Private — KEPCO E&C PoC 전용

Name		Name	Last commit message	Last commit date
.claude		.claude
.github		.github
.moai		.moai
apps		apps
deployments		deployments
docs		docs
pipelines		pipelines
pkg		pkg
schemas		schemas
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.mcp.json		.mcp.json
.pre-commit-config.yaml		.pre-commit-config.yaml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
tsconfig.json		tsconfig.json
uv.lock		uv.lock

Navigation Menu

Repository files navigation

iroum-ax

프로젝트 상태

빠른 시작

서버 부팅

빠른 시작

빠른 설정

구조 요약

웹 대시보드 (SPEC-AX-WEB-001)

데모 화면

웹 대시보드 시작

웹 기술 스택

기술 스택

아키텍처 & 설계

개발 명령어

다음 단계 (후속 SPEC)

웹 대시보드 확장

플랫폼 확장

아키텍처 결정 기록 (ADR)

라이선스

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

iroum-ax

프로젝트 상태

빠른 시작

서버 부팅

빠른 시작

빠른 설정

구조 요약

웹 대시보드 (SPEC-AX-WEB-001)

데모 화면

웹 대시보드 시작

웹 기술 스택

기술 스택

아키텍처 & 설계

개발 명령어

다음 단계 (후속 SPEC)

웹 대시보드 확장

플랫폼 확장

아키텍처 결정 기록 (ADR)

라이선스

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages