공식 egovframe-ai-rag 샘플 기반 AI RAG 챗봇(문서 업로드→임베딩→하이브리드 검색→LLM 응답)을 기존 Boot 프로젝트에 조립합니다. 소스·설정(application-ai.yml 프로필)·UI·인프라를 복사하고 pom에 누락 의존성만 마커 구간으로 삽입합니다(백업 생성, 제거 시 원복). 기존 파일과 충돌하면 아무것도 쓰지 않고 거부합니다. dryRun=true로 먼저 미리볼 수 있습니다. v1.20: Boot parent 가 5.1.0 이상이면(base=auto) 샘플 복사 대신 5.1.0 실행환경 AI 모듈(egovframe-rte-ai-core + Spring AI/LangChain4j 어댑터)을 쓰는 조립물을 프로젝트 패키지에 생성합니다 — 문서 추출(HWP·HWPX·DOCX·PDF·Markdown, 추출 한도)→정규화→한국어 문장 청킹→개인정보 마스킹→PGVector 재색인, 질의는 프롬프트 인젝션 가드→검색→OpenAI 호환 모델 응답(POST /ai/documents·/ai/ask), 접속 정보는 환경 변수 EGOV_AI_*.

공통컴포넌트를 골라 기존 프로젝트에 조립합니다. 의존 컴포넌트를 포함해 소스·매퍼·JSP를 복사하고, database 지정 시 DB DDL·DML 스크립트도 복사합니다. 기존 파일과 충돌하면 아무것도 쓰지 않고 거부합니다. dryRun=true로 먼저 미리볼 수 있습니다.

레시피 하나를 골라 프로젝트 생성 → 공통컴포넌트(필요 시 AI 계층) 조립까지 순차 실행합니다. dryRun=true로 전체 계획을 먼저 미리볼 수 있습니다.

생성한 eGovFrame 프로젝트를 실제로 빌드(컴파일·테스트·패키지)하고 결과를 구조화해 반환합니다. 빌드도구(maven/gradle)와 래퍼(mvnw/gradlew)를 자동 감지하고, 컴파일·테스트 오류를 파일·라인 단위로 파싱합니다. 원격 저장소 일시 장애(5xx·연결 끊김)는 failureKind=repository-unavailable 로 구분하고 -U 로 다시 실행합니다(retryTransient). dryRun으로 실행 예정 명령만 미리볼 수 있습니다. (생성→검증 루프 완성)

프로젝트의 Maven/Gradle 의존성(resolve=true 면 빌드 도구로 해석한 전이 의존성까지, 트리 경로와 선언·해석 버전 차이 포함)을 공식 5.x parent(egovframe-web-config-parent·egovframe-boot-starter-parent)가 관리하는 기준 버전, Spring Boot BOM 전체(spring-boot-dependencies + import 한 단계), RTE 모듈 18종의 전이 의존성과 대조해 기준 충족/기준 미만/parent 관리/전환 대상(3.x·4.x RTE, javax 좌표)/교체 필요(DBCP 1.x·Log4j 1.x·Jackson 1·Ehcache 2 등)/벤더 배포(국내 DBMS·GPKI 등)/기준 없음 으로 분류하고 항목마다 기준 출처(parent 직접·계열·Boot BOM·RTE 전이)를 적으며, 5.x parent 사용 여부와 Java 버전, 보안 설정 존재 여부(sec.security 컴포넌트·CSRF·XSS 필터·보안 헤더·HTTPS 저장소)를 파일·라인 근거와 함께 보고합니다. 기본은 오프라인(동봉 기준 catalog/dependency-baseline.json)이며 offline=false 일 때만 OSV(api.osv.dev)로 알려진 취약점을 조회합니다. 디스크를 변경하지 않습니다. 멀티 모듈 작업공간이면 모듈별로 판정하고(모듈 parent·Gradle 버전 변수·공식 parent BOM) 모듈 요약을 함께 냅니다. parent 5.1.0 프로젝트는 5.1 기준(BOM egovframe-rte-root, GitHub 태그 없이 저장소에 배포된 버전)으로 판정하고, -egov.N 재빌드 좌표는 원 버전으로 비교·OSV 조회합니다.

"기동은 되는데 운영에서 터지는" 설정을 운영 투입 전에 점검합니다(읽기 전용, 값을 고치지 않고 바뀔 줄을 제안). 운영 설정 세트 — Boot 는 application + application-prod(production·release·ops 중 있는 것, profile 로 지정).* 만 보고 dev·local·test 프로파일은 뺍니다, Classic 은 globals.properties·context-*.xml·web.xml·log4j2/logback.xml — 에서 규칙 데이터(catalog/operations-rules.json, 규칙마다 출처 명시) 17종을 평가합니다: SQL 로깅 프록시 드라이버(log4jdbc·P6Spy) 잔존, DEBUG/TRACE 로그 수준, 콘솔 전용 로그(로테이션 없음), spring-boot-devtools, 내장 DB(HSQL·H2) 잔존, 커넥션 풀 크기·타임아웃·수명·누수 감지 미설정, 세션 타임아웃 없음/60분 초과, 세션 쿠키 http-only·secure, 업로드 상한 없음/100MB 이상·허용 확장자 없음, 업로드 경로 상대·/tmp·웹 루트, 오류 상세 노출(include-stacktrace·show-sql·debug), error-page 없음, actuator 전체 노출, 표준프레임워크 개발 플래그(LocalIp 127.0.0.1·Hsql.AutoInit), 운영 프로파일 없음, 하드코드 비밀값(보안약점 규칙과 같은 판정, externalize_egovframe_config 참조). 결과는 점검표(규칙 × 통과/미달/해당 없음)·미달 항목(파일·줄·현재 값·제안·근거)·등급 A–D(규칙 단위: A 높음 0·중간 ≤1, B 높음 ≤1·중간 ≤3, C 높음 ≤3, D). 예외는 .egovframe-ops-ignore.json(rule·path·reason·reviewer). 공식 운영 기준 문서가 없어 근거는 공식 템플릿 기본값 실측·HikariCP/Spring Boot/Tomcat 문서입니다. 평가서(generate_egovframe_report)에도 「운영 준비」가 들어갑니다. 부하 시험·운영 WAS(JEUS 등)·OS/DB 서버 설정은 보지 않습니다.

이미 만든 CycloneDX 또는 SPDX 2.x JSON SBOM 을 제출물로서 점검합니다(SBOM 파일은 바꾸지 않음, 형식은 자동 판별). (1) 최소 요소 7종 — 공급자·구성요소명·버전·고유식별자(purl/cpe)·의존관계·작성자·생성 시각(NTIA 최소 요소 = 국내 SW 공급망 보안 가이드라인 핵심 구성요소)을 component 마다 세어 '제출 가능/보완 필요'와 빠진 component 를 보고 (2) 빌드 도구 없이 purl 만으로 기준 판정을 다시 해 생성 당시와 달라진 판정을, offline=false 면 OSV 를 다시 조회해 생성 이후 새로 알려진 취약점을 보고(운영 중 주기 점검) (3) baselinePath(이전 SBOM)를 주면 추가·제거·버전 변경·판정 변화·새 취약점을 비교 (4) vex=true 면(CycloneDX 입력만) CycloneDX VEX 초안(기본 sbom/vex.cdx.json)을 씁니다 — 새 취약점은 analysis.state=in_triage, affects 는 BOM-Link 로 원본 SBOM 참조, 기존 VEX 에 사람이 적은 판단(not_affected·exploitable 등)은 보존하고 새 취약점만 추가합니다(dryRun=true 면 미리보기). 2027년 공공 SBOM 제출 제도화 대비.

행정안전부·KISA 「소프트웨어 개발보안 가이드」(2021) 구현단계 보안약점 중 정적 패턴으로 오탐을 통제할 수 있는 항목을 소스에서 찾습니다 — SQL 삽입(MyBatis ${…}·iBATIS $…$·JDBC 문자열 연결), 크로스사이트 스크립트(요청 값·EL param/header/cookie 무이스케이프 출력, <c:out escapeXml="false">), 경로 조작, 신뢰되지 않는 URL 자동접속, 운영체제 명령어, XML 외부개체, 취약한 해시·암호, 보안 문맥의 부적절한 난수, 코드·설정의 하드코드된 중요정보, HttpOnly·Secure 없는 쿠키, printStackTrace, 빈 catch, 역직렬화, 남은 디버그 출력. 규칙은 catalog/secure-coding-rules.json 데이터이고 주석은 무시합니다. 항목마다 파일·라인·CWE·등급·조치와 출처(공통컴포넌트 원본·수정본·매니페스트 없음·프로젝트 코드·테스트)를 냅니다. 예외는 .egovframe-secure-ignore.json(사유·검토자 필수), baselinePath(이전 JSON 결과·SARIF)와 비교해 새 항목 표시, format=sarif 또는 sarifPath 로 SARIF 2.1.0(GitHub code scanning 등). v1.5: 메서드 안 데이터 흐름(요청 파라미터·헤더·쿠키·Spring 바인딩 값 → 대입·결합·append → JDBC·파일 경로·OS 명령·리다이렉트)으로 등급을 올리거나 내리고 변수를 거친 미탐을 찾습니다(메서드 간 흐름은 보지 않음). v1.7: HTMLTagFilter 가 등록돼 있으면(요청 값을 엔티티로 저장) c:out escapeXml="false" 를 낮음으로 보고 사유를 적습니다. 고칠 수 있는 항목은 fix_egovframe_secure_coding 으로. 패턴 기반 진단 보조이며 공인 진단을 대체하지 않습니다.

전자정부 표준프레임워크 공식 템플릿으로 새 프로젝트 골격을 생성합니다. 공식 GitHub 템플릿을 내려받아 projectName/groupId/DB 타입을 적용합니다. dryRun=true로 먼저 미리보기할 수 있습니다. alignParent=true 면 생성 직후 5.x parent·RTE 버전을 최신 5.0.x 로 맞춥니다(공식 Initializr 템플릿은 parent 5.0.0·5.0.1). rteVersion 으로 다른 5.x 버전(예: 태그 전 5.1.0)을 고를 수 있습니다.

이 서버의 도구들이 내려받는 외부 호스트(codeload.github.com·raw.githubusercontent.com·media.githubusercontent.com·maven.egovframe.go.kr·repo1.maven.org·registry.npmjs.org·api.osv.dev)에 DNS 조회와 HEAD 요청을 실제로 보내 접속 가능 여부·소요 시간·실패 종류(DNS·타임아웃·TLS·프록시 인증·거부)를 보고하고, 환경에 맞는 처방(HTTPS_PROXY+NODE_USE_ENV_PROXY=1, NODE_OPTIONS=--dns-result-order=ipv4first, NODE_EXTRA_CA_CERTS)을 bash/cmd/PowerShell 명령으로 안내합니다. 프로젝트 생성·컴포넌트 조립이 타임아웃으로 실패할 때 먼저 실행하세요. 파일을 쓰지 않으며 프로젝트 디렉터리도 필요 없습니다.

기존(스캐폴딩 도구로 만들지 않은 것 포함) 전자정부 표준프레임워크 프로젝트를 스캔해 빌드시스템·RTE 버전·DbType·설치된 공통컴포넌트(카탈로그 pathPrefixes 지문)·설정 문제를 진단합니다. 디스크를 변경하지 않는 읽기 전용입니다.

공통컴포넌트 하나의 상세(설명·직접/전이 의존성·이 컴포넌트에 의존하는 컴포넌트·참조 테이블·가이드 문서 링크·설치 명령)를 한 번에 반환합니다. (읽기 전용)

설정 파일(globals.properties·application.properties/yml·context-.xml)의 DB 비밀번호·비밀 값을 저장소 밖으로 옮깁니다. 판정은 check_egovframe_secure_coding 의 hardcoded-config-password 규칙과 화이트리스트(.egovframe-secure-ignore.json)를 그대로 써서 두 도구의 결과가 같습니다(XML 의 은 주석을 뺀 채 추가로 찾음). 키를 읽는 방식에 따라 — Spring 자리표시자·Boot Environment 로 읽는 키는 값을 지우고 ${EGOV_…_PASSWORD} 자리표시자로(env), 표준프레임워크 암호화 값(Globals..Password)은 그대로 두고 복호화 키가 든 egov-crypto-config.properties 의 algorithmKey·algorithmKeyHash 를 지운 뒤 globals.properties 에 Globals.CryptoConfigPath=${EGOV_CRYPTO_CONFIG:} 를 넣어 외부 파일에서 읽게 하며(crypto-path, runtime 5.x), deploy/secrets/egov-crypto-config.properties.example 을 만듭니다. EgovProperties.getProperty("…") 처럼 파일을 직접 읽는 키(Globals.File.algorithmKey 등)와 4.x context-crypto.xml 의 키는 자리표시자가 풀리지 않으므로 사유와 함께 수동 항목으로 냅니다. generate_egovframe_deploy 산출물(deploy/.env.example·docker-compose.yml·k8s Secret)이 있으면 환경 변수 자리를 추가합니다. 기본 dryRun(바뀔 줄은 가린 값으로), 적용은 파일 트랜잭션(원본은 migration-backup/ — 비밀 값이 들어 있으니 저장소에 넣지 마세요)이고 적용 뒤 보안약점 규칙 전·후 수를 보고합니다. verify=true 면 원래 값을 환경 변수로 주고 verify_egovframe_startup 으로 띄워 설정 해석에 실패하면(config-missing) 되돌립니다. 결과·로그에 원래 값은 적지 않습니다.

check_egovframe_dependencies 가 찾기만 하던 의존성 문제를 규칙으로 정할 수 있는 만큼 pom.xml(멀티 모듈 포함)에서 고칩니다. 순서: (1) parent 상향 — 공식 parent 5.x 를 target(기본 권장 버전)으로(migrate_egovframe_project target 의 자동 항목), (2) 고정 해제 — parent(또는 Boot BOM)가 관리하는 좌표에 그보다 낮게 적은 을 지워 parent 에 맡김(major 가 다르면 수동), (3) 좌표 교체 — 좌표만 바뀌고 패키지가 같은 것(mysql-connector-java→mysql-connector-j, ojdbc→ojdbc11, xbean→xmlbeans), (4) 취약 버전 상향 — 직접 적은 버전(리터럴 또는 같은 계열 좌표만 쓰는 버전 속성)이 OSV 에 걸리면 모든 권고를 피하는 가장 낮은 같은 major 정식 릴리스로(저장소 maven-metadata 로 실제 배포 버전 확인, major 가 바뀌거나 수정 버전이 없으면 수동). parent 가 관리하는 버전·전이 의존성의 취약점은 고치지 않고 보고합니다. 결과에 선언 좌표 기준 전·후 취약점 수를 적습니다. 기본 dryRun(계획·변경 미리보기), 적용은 파일 트랜잭션(원본은 migration-backup/<시각>-deps-fix-…/)이며 compile 로 확인해 실패하면 모두 되돌립니다. Gradle 은 리터럴 'g:a:v' 의 고정 해제·취약 버전 상향만. 오프라인 번들(EGOVFRAME_OFFLINE_BUNDLE)이 있으면 OSV 를 번들로 판정합니다.

check_egovframe_secure_coding 이 찾은 항목 중 고친 결과를 규칙으로 정할 수 있는 것만 고치고, 나머지는 사유와 함께 수동 항목으로 냅니다. xss-cout-unescaped: 줄바꿈을 로 바꾸는 값은 fn:escapeXml 로 먼저 감싸고, 단순 속성 값은 escapeXml="false" 를 지웁니다(HTML 편집기 값일 수 있는 본문 필드는 수동, HTMLTagFilter 가 등록돼 있으면 요청 값이 엔티티로 저장되므로 ignoreHtmlTagFilter=true 가 아니면 모두 수동). print-stack-trace·debug-code: 클래스의 로거(SLF4J·Commons Logging·Log4j 2/1·Lombok)로 바꿉니다(로거가 없거나 정적 문맥에서 인스턴스 로거면 수동). cookie-flags: Secure·HttpOnly 는 동작을 바꾸므로 제안만. 공통컴포넌트 출처·테스트는 기본 제외(includeComponents·includeTests). 기본 dryRun(바뀔 줄과 재점검 결과), 적용은 파일 트랜잭션(원본은 migration-backup/)이며 재점검이 계획과 다르면(고친 항목만 사라지고 새 항목·다른 규칙 변화가 없어야 함) 적용하지 않습니다.

프로젝트를 진단해 AI 코딩 도구(Claude Code·Copilot·Cursor 등)용 AGENTS.md 를 생성합니다 — 빌드·테스트 명령(래퍼 감지), RTE 버전과 5.x 전환 상태, DbType, 기본 패키지·설정 디렉터리, 설치 공통컴포넌트(매니페스트 관리 여부), 지켜야 할 규칙(좌표·백업 디렉터리·비밀 정보·의존성 기준), 사용할 수 있는 MCP 도구. 기존 파일은 overwrite=true 가 아니면 거부하고, dryRun=true 면 내용만 돌려줍니다. 한국어(기본)·영어.

프로젝트에 CI 설정을 생성합니다 — platform=github(.github/workflows/egovframe-ci.yml, 기본)·gitlab(.gitlab-ci.yml)·jenkins(Jenkinsfile, Declarative). 빌드도구(maven/gradle) 자동 감지, JDK 지정, 빌드·테스트(GitLab 은 JUnit 리포트). supplyChain=true 면 이 서버의 CLI(npx egovframe-scaffold-mcp)로 SBOM 생성 → 최소 요소 7종 점검(sbom-check --fail-on minimum) → 전환 준비도 평가서(failOn 기준, 기본 supplyChain:D)를 돌려 기준을 넘으면 실패하고 보고서·SBOM 을 아티팩트로 남기는 공급망 게이트를 추가합니다(GitHub 은 PR 요약에 등급, GitLab 은 CycloneDX 리포트). npmRegistry(사내 npm 레지스트리)·offlineBundle(러너에서 본 오프라인 번들 경로)은 환경 변수로 넣습니다. Maven 빌드 단계는 원격 저장소 일시 장애(5xx·연결 끊김)일 때만 -U 로 최대 3회 다시 실행하고, mavenMirror 로 사내 미러를 지정할 수 있습니다. dryRun으로 내용만 미리볼 수 있고, 실제 생성 시 기존 파일이 있으면 덮어쓰지 않고 거부합니다. delivery=true 면 게이트 끝에 납품 패키지 단계(deliver --write → egovframe-delivery/)를 더해 아티팩트로 남깁니다.

공식 eGovFrame Initializr 설정 템플릿(21종, 오프라인 동봉)으로 Spring 설정 파일을 생성합니다 — datasource(DBCP/C3P0/JDBC·JNDI), transaction(datasource/JPA/JTA), cache(Ehcache), logging(log4j2 console/file/rolling/time-rolling/jdbc), scheduling(Quartz job/trigger/scheduler), idGeneration(sequence/table/uuid), property. 형식은 xml(Spring XML)·javaConfig(@Configuration 클래스)·yaml·properties(logging 만). 필드를 생략하면 Initializr 웹뷰 폼과 같은 기본값을 쓰고, 기존 파일이 있으면 덮어쓰지 않고 거부합니다. 템플릿별 필드·기본값·선택지는 리소스 egovframe://catalog/config-templates 에서 확인하거나 dryRun 결과의 context 로 볼 수 있습니다.

eGovFrame Development의 공식 CRUD wizard 입력 체계에 맞춰 VO·Mapper(XML)·Service·Controller·JSP(선택)·JUnit 5 테스트(선택) 골격을 생성합니다. Classic XML과 Boot REST 프로필을 지원하며, 전체 파일 충돌을 먼저 검사해 하나라도 존재하면 아무것도 쓰지 않습니다. v1.4: ddl 에 CREATE TABLE 문을 주면 컬럼·타입·기본키·NOT NULL·자동 증가·COMMENT 를 읽어 필드를 만들고(COMMENT·DEFAULT 안의 콤마·괄호·'primary key' 문구에 속지 않음), search 로 방언 중립 LIKE() 검색과 이스케이프된 검색 필드를 더합니다. v1.8: paging 으로 방언별 목록 페이징(LIMIT/OFFSET 또는 공통컴포넌트와 같은 ROWNUM 감싸기), classic 화면의 PaginationInfo·ui:pagination, boot REST 의 page·size 응답을 더합니다(방언은 dialect 또는 Globals.DbType).

프로젝트 진단(빌드 도구·패키징·Boot 여부·웹·actuator·DbType·설정 파일)으로 컨테이너·배포 산출물을 만듭니다 — Dockerfile(멀티 스테이지: Maven/Gradle 빌드 → Classic war 는 Tomcat 10.1(Servlet 6.1 이상이면 11.0)에 ROOT 로 풀어서, Boot jar 는 eclipse-temurin JRE 로; 비루트·HEALTHCHECK·Asia/Seoul·UTF-8, buildInImage=false 면 미리 빌드한 산출물), .dockerignore, deploy/docker-compose.yml(앱 + DbType 별 DB 컨테이너 mysql·mariadb·postgres, 템플릿 DDL·DATA 초기화, 상용 DB 는 연결 정보만), Kubernetes 매니페스트(deploy/k8s/.yaml — Deployment(startup·readiness·liveness 프로브, 비루트 securityContext, 리소스)·Service·ConfigMap·Secret·선택 Ingress). DB 설정은 Boot 는 Spring 환경 변수(Globals.mysql.Url → GLOBALS_MYSQL_URL), Classic 은 globals.properties 사본을 볼륨·Secret 으로 덮어씁니다. imageRegistry 로 기반 이미지를 사내 레지스트리(폐쇄망)에서 받습니다. 새 파일만 쓰고(기존 파일 거부) dryRun(기본)은 내용만 보여 줍니다. 멀티 모듈·라이브러리 jar·빌드 파일 없는 프로젝트는 이유를 돌려줍니다. 멀티 모듈 작업공간(Maven ·Gradle include·루트 빌드 파일 없는 독립 프로젝트 묶음)이면 서비스 모듈마다 이미지(자체 Dockerfile 은 그대로)와 하나의 docker-compose·서비스별 Kubernetes 매니페스트를 만들고, 설정의 localhost 참조(설정 서버·디스커버리·DB·메시지 브로커·캐시)를 서비스 이름으로 바꿉니다(모듈 설정은 환경 변수, 설정 서버 저장소는 사본). modules 로 일부 서비스만 고릅니다. v1.16: observability="otel" 이면 OpenTelemetry Java 에이전트(고정 버전·sha256 확인, 폐쇄망은 빌드 컨텍스트 deploy/otel/ 의 jar 또는 --build-arg OTEL_AGENT_URL)를 이미지에 두고 compose·Kubernetes 가 JAVA_TOOL_OPTIONS·OTEL_SERVICE_NAME·OTEL_EXPORTER_OTLP_ENDPOINT·OTEL_RESOURCE_ATTRIBUTES 로 붙여 OpenTelemetry Collector(core 배포판, Apache-2.0)로 trace·metric·log 를 보냅니다 — 수집기는 기본 debug 출력, 기관 백엔드(otlp_http·prometheus)는 설정 주석, 저장·대시보드(AGPL 스택)는 동봉하지 않음.

프로젝트 리포트를 Markdown(또는 format=json)으로 만듭니다. sections="components"는 설치 공통컴포넌트·참조 테이블·가이드 문서 링크·이슈, sections=["assessment"]는 5.x 전환 준비도 평가서 — (1) 개요(빌드 도구·RTE 세대·parent·Java·공통컴포넌트) (2) 전환 범위(migrate 진단 요약: 자동/수동·종류별·재조립 권고·예상 수동 작업 상위 N) (3) 의존성(기준 판정 집계·조치 목록, resolve=true 면 전이 포함, offline=false 면 OSV 취약점) (4) 보안 설정 점검 (5) SBOM 요약(sbomPath 에 있으면) (6) 등급과 근거 — 전환 난이도·공급망 상태를 각각 A–D 로 매기고 산식(요인·구간·점수)을 리포트에 그대로 적어 사람이 재계산할 수 있게 합니다. 비용·공수는 산정하지 않습니다. outputPath 를 주면 프로젝트 안에 새 파일로만 저장하고(기존 파일 거부, transaction), 그 외에는 디스크를 바꾸지 않습니다.

Maven/Gradle 프로젝트의 SBOM 을 CycloneDX 1.6 JSON(기본) 또는 SPDX 2.3 JSON(bomFormat=spdx-json — 패키지·DEPENDS_ON 관계·purl·공급자·작성자·생성 시각)으로 만듭니다(빌드 파일 변경 없음). Maven 은 cyclonedx-maven-plugin(makeAggregateBom, 해시·라이선스 포함), Gradle 은 해석된 의존성 트리로 문서를 구성합니다. enrich=true(기본)면 component 마다 기준 판정(egovframe:status·basis·baseline)을 properties 로 붙이고, offline=false 면 OSV 로 알려진 취약점을 vulnerabilities[] 로 넣습니다. 출력은 프로젝트 안 경로(기본 sbom/bom.cdx.json)만 허용하고 기존 파일은 overwrite=true 가 아니면 거부하며, dryRun(기본)은 실행 없이 계획만 돌려줍니다. 2027년부터 단계화되는 공공기관 SBOM 등록·제출에 쓸 수 있는 표준 형식입니다.

컴포넌트의 공식 가이드 문서(표준프레임워크 포털 egovframe-docs)를 가져옵니다. 문서가 여러 건이면 목록을 함께 반환하며 docIndex로 선택할 수 있습니다.

선택 설치를 지원하는 공통컴포넌트 카탈로그를 반환합니다 (저장소 스캔으로 자동 생성, scripts/generate-catalog.mjs).

큐레이션된 레시피(템플릿+컴포넌트 번들) 목록을 반환합니다. apply_egovframe_recipe로 한 번에 조립할 수 있습니다.

사용 가능한 전자정부 표준프레임워크 프로젝트 템플릿 목록을 반환합니다.

프로젝트를 읽어 테이블 → 매퍼 XML(네임스페이스, DB 별 사본은 하나로) → DAO/Mapper 인터페이스 → Service → Controller → URL → 화면(JSP·Thymeleaf)의 구조 지도를 만듭니다(읽기 전용, 정적 해석 — 파일·정규식·심볼 테이블, 런타임 추적 없음). 표준프레임워크 규약(EgovComAbstractDAO 의 "네임스페이스.문장id" 문자열, @Resource(name=…) 빈 이름, *ServiceImpl)과 Spring 어노테이션(@Mapper·@Autowired·@GetMapping 등)을 둘 다 읽고, 공통컴포넌트 파일은 카탈로그 경로 접두어로 컴포넌트를 표시합니다. impact 로 한 노드의 영향을 거리순으로 — table(COMTNBBS) 은 사용하는 매퍼·서비스·컨트롤러·URL·화면(위로), url(/cop/bbs/selectArticleList.do)·view 는 거꾸로 테이블까지(아래로) + 링크하는 화면 한 단계, class 는 양쪽. 인수인계 표 3종(화면 목록: URL·Controller·화면 / 프로그램 목록: Controller·Service·DAO·매퍼 / DB 접근 표: 테이블 × C·R·U·D × 매퍼)과 고아(호출 없는 매퍼·문장, URL 없는 Controller, 미참조 컴포넌트 테이블), 해석 실패율(동적 SQL ${…} 테이블·찾지 못한 뷰)을 함께 냅니다. format=json 은 전체 그래프(nodes·edges·statements·handover), mermaid 는 components 또는 impact 로 좁힌 200 노드 이하만. 동적 SQL 의 테이블 이름·프런트(React) 라우팅·리플렉션은 보지 않습니다.

표준프레임워크 3.x/4.x 프로젝트를 5.x(Jakarta EE 9+, Spring 6, Java 17) 로 옮기기 위해 바꿔야 할 것을 파일·라인 단위로 진단하고(1단계), apply=true 이면 auto 항목을 실제로 치환합니다(2단계). 진단: RTE Maven 좌표(egovframework.rte → org.egovframe.rte:egovframe-rte-)·패키지(egovframework.rte. → org.egovframe.rte.)·5.x 에서 이름이 바뀌거나 제거된 클래스·javax→jakarta 패키지와 의존성·web.xml 스키마·제거된 egov- XML 네임스페이스·교체 필요 라이브러리, 항목마다 auto(기계 치환 가능)/manual(코드 수정 필요). 적용: apply=true 는 dryRun=true(기본)면 파일별 변경 미리보기만 돌려주고, dryRun=false 면 auto 항목을 하나의 transaction 으로 치환하며 원본을 migration-backup/<시각>/ 에 보관하고 migration-plan.json 을 남깁니다(중간 실패 시 작업 전 상태로 복구). manual 항목은 건드리지 않고 결과에 남깁니다. verify=true 는 3단계(검증): 적용 뒤 compile 을 실행해 컴파일 오류를 수동 항목과 연결하고 "이 항목을 처리하면 해결될 오류 수" 순으로 작업 목록을 만듭니다. 3.x 공통컴포넌트 소스가 섞여 있으면 컴포넌트 단위 재조립 권고를 내고 skipComponents 로 치환에서 뺄 수 있습니다. 규칙은 egovframe-runtime·egovframe-common-components 태그 비교로 만든 동봉 카탈로그(catalog/migration-rules.json)에서 읽습니다. target 에 5.0.2 같은 5.0.2·5.1.0 같은 5.y.z 를 주면 이미 5.x 인 프로젝트의 갱신 모드가 됩니다(5.1.0 은 GitHub 태그 없이 저장소에 배포된 버전 — 근거는 sources jar 비교): parent·RTE 버전 속성·RTE 의존성 리터럴 버전과 예전 parent 기본값을 그대로 덮어쓴 속성은 auto, 그 사이 바뀐 RTE API·동작(보안 설정 Bean 시그니처, 엑셀 수식 주입 방지, XML XXE 차단 등)을 프로젝트가 참조하는 곳과 공통컴포넌트 최신 유지(upgrade·reassemble 안내)는 manual 로 보고하며, apply·dryRun·verify 는 전환과 같게 동작합니다(백업에 update-plan.json, 규칙 catalog/update-rules.json).

공통컴포넌트·프로젝트의 DB 스크립트를 개발·테스트 DB 에 바로 넣을 수 있게 준비합니다. 원본은 자동으로 고릅니다 — 조립 선별본(scripts/egovframe-components//, 매니페스트 설치 순서) → 공통컴포넌트 전체(script/ddl·dml//) → 이름 규칙(ddl·schema / dml·data), 또는 scripts 로 지정. 문장 단위로 나눠 스키마·데이터로 가르고, 겹친 문장을 한 번만 두고, 외래키·뷰 참조 순서로 테이블을 정렬하며(데이터도 부모 행이 먼저), 선별본이 참조하는데 빠진 테이블(예: COMTCCMMNDETAILCODE → COMTCCMMNCODE)은 공통컴포넌트 통합 스크립트에서 보완합니다. MySQL·MariaDB 는 테이블마다 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci 와 스크립트 머리의 SET NAMES utf8mb4 로 클라이언트 문자셋과 무관하게 한글이 같게 저장되게 하고(Docker 초기화의 한글 이중 인코딩·latin1 클라이언트의 정렬 규칙 충돌), PostgreSQL 은 client_encoding UTF8. 산출물은 scripts/egovframe-db//01-schema.sql·02-data.sql 과 docker-compose.db.yml(MySQL 8.4·MariaDB 11.4·PostgreSQL 16, 접속 정보는 프로젝트 설정), 적재 명령(bash·cmd). Oracle·Tibero·Altibase·CUBRID 는 스크립트·명령만. run=true 면 Docker 로 DB 를 띄워 넣고 테이블 수·필수 행(관리자 계정·메뉴·공통코드)·한글 왕복을 확인한 뒤 컨테이너를 지웁니다(keep=true 면 남김). 기본 dryRun, 기존 파일은 덮어쓰지 않습니다(다른 내용이면 거부). 운영 DB 적재·스키마 이관은 하지 않습니다.

감리·검수에 내는 산출물을 새 디렉터리 하나에 모읍니다 — 전환 준비도 평가서, 의존성 조치 목록, SBOM(CycloneDX 1.6·SPDX 2.3), SBOM 점검과 VEX 초안, 보안약점 결과와 SARIF, 컨테이너·배포 산출물, (지정 시) 빌드 결과. delivery-manifest.json(파일별 sha256·크기, 도구 버전, 입력 지문, 전체 지문 rootHash)과 목차 index.md 를 쓰고, 실패한 항목은 빼지 않고 이유와 함께 목차에 남깁니다. previousDelivery 를 주면 이전 차수와 비교한 diff.md(등급·SBOM 구성요소와 버전·새/해소 취약점·새/해소 보안약점)를 만들고 이전 VEX 의 사람 판단을 보존합니다. verify=true 면 받은 패키지(outputDir)의 지문을 다시 계산해 변조·누락을 봅니다. 프로젝트는 읽기만 하고(SBOM 도 프로젝트에 쓰지 않음) outputDir 는 비어 있어야 합니다. dryRun(기본)은 계획만, zip=true 면 .zip 도 만듭니다.

망분리(폐쇄망) 개발 환경용 오프라인 번들을 인터넷 PC 에서 만듭니다. OSV Maven 취약점 전체 덤프·고정 공통컴포넌트 아카이브(sha256 검증)·Initializr zip 템플릿(고정 지문)·재조립용 공식 공통컴포넌트 태그 미러를 한 디렉터리에 담고 bundle-manifest.json(파일별 sha256·크기·출처 URL·받은 시각)을 씁니다. 새(또는 빈) 디렉터리에만 쓰며 dryRun(기본)은 받을 목록만 보여 줍니다. 폐쇄망 PC 에서 환경변수 EGOVFRAME_OFFLINE_BUNDLE 에 옮긴 경로를 지정하면 다운로드는 번들 파일을 지문 검증 후 쓰고, offline=false 의 OSV 조회는 로컬 덤프로 판정하며(스냅숏 기준일 표시·30일 넘으면 경고), 재조립은 번들 미러를 씁니다. Maven 의존성 jar 는 담지 않습니다(기관 저장소 미러 사용).

3.x/4.x(또는 이전 5.x) 프로젝트에 복사돼 있는 공통컴포넌트 소스를 카탈로그 고정 버전(현재 v5.0.7)으로 다시 조립합니다. (1) 프로젝트 파일의 git blob id 를 공식 egovframe-common-components 후보 태그(좌표 세대별)와 대조해 원본 태그를 식별하고(파일 내용을 내려받지 않음, sourceTag 로 지정 가능) (2) 원본·현재·목표로 파일마다 목표와 같음/원본 그대로(교체)/사용자 수정/5.x 신규/5.x 에서 제거/원본 미확인/사용자 추가를 판정한 뒤 (3) dryRun=false 면 하나의 transaction 으로 목표 파일을 쓰고(아카이브 sha256 검증), 5.x 에 없는 원본 파일은 백업 후 지우고, 사용자 수정 소스는 교체하되 원본 대비 변경을 unified diff 패치로 보존하며(설정·자산 파일은 사용자본을 유지하고 목표본을 참고로 저장) 매니페스트를 기록해 이후 upgrade·validate·remove 도구가 적용되게 합니다. 백업·패치·reassemble-plan.json 은 migration-backup/<시각>-reassemble-*/ 에 남고, 작업 목록(패치 다시 반영·5.x 제거 파일·설정 비교)을 돌려줍니다. verify=true 면 적용 뒤 compile 을 실행해 오류를 작업 목록 파일에 붙입니다. 원본 태그 비교에 git 이 필요하며 캐시는 EGOVFRAME_CACHE_DIR(기본 ~/.cache/egovframe-scaffold-mcp)에 둡니다. v1.12: reapply=true 면 사용자 수정 파일(소스·설정)을 원본·현재·목표 3-way(git merge-file)로 합쳐 충돌 없는 것만 그 결과로 쓰고, 충돌·이진은 지금처럼 목표본 + 패치 + 작업 목록(충돌 hunk 수)으로 남깁니다 — 파일에 충돌 표식을 넣지 않습니다. verify=true 와 함께 쓰면 합친 파일에서 컴파일 오류가 나는 것은 목표본으로 되돌립니다.

프로젝트를 건드리지 않고 사본에서 5.x 전환을 미리 돌려 봅니다. 사본(EGOVFRAME_CACHE_DIR/rehearsal, 빌드 산출물·VCS·백업 제외)에서 (1) 공통컴포넌트 재조립(원본 태그 식별이 깨지지 않도록 전환 적용보다 먼저) (2) 전환 자동 항목 적용 (3) 컴파일 — Maven 은 javac 를 fork 해 -Xmaxerrs 로 오류 100개 상한 없이 모두 셈 (4) 사본 pom 을 공식 공통컴포넌트 고정 태그 pom 기준(parent·누락 좌표·버전·scope·parent 관리 속성)으로 맞춘 뒤 다시 컴파일합니다. 두 시점의 오류 수, 누락 패키지와 후보 좌표, 같은 파일의 연쇄 오류, 남는 수동 항목·파일, 사라지는 오류 순 작업 목록, 사본에 적용한 pom 패치를 돌려주고, 실행 전후 디렉터리 지문으로 원본 불변을 확인합니다. 최근 결과는 평가서 6절에 실측으로 표시됩니다. keepWorkspace=true 면 사본을 남깁니다.

add_egovframe_components로 조립한 컴포넌트를 제거합니다. 설치 매니페스트에 기록된 파일만 삭제하며, 다른 설치 컴포넌트가 의존하거나 설치 시점 hash와 달라진 파일은 기본 거부합니다. force=true는 remove-backup/에 사본을 만든 뒤 트랜잭션 제거하며, dryRun 미리보기를 지원합니다.

키워드로 공통컴포넌트를 검색합니다 (id·이름·설명·카테고리 부분 일치, 점수순 상위 10건).

공식 가이드 문서(egovframe-docs) 인덱스를 키워드로 검색합니다. 기본은 오프라인 인덱스 검색(제목·경로·연계 컴포넌트·카테고리 점수순)이며, fetchTop>0이면 상위 결과의 문서 본문을 내려받아 스니펫도 함께 제공합니다.

여러 전자정부 표준프레임워크 프로젝트의 전환 준비도·공급망·보안약점·운영 준비를 한 표로 모읍니다(새 분석 없이 평가서를 모으기·비교·표). 입력 inputs 는 디렉터리 목록(끝이 /* 면 그 아래 디렉터리 전부)이고 종류를 자동 판별합니다 — 프로젝트(pom.xml·build.gradle: generate_egovframe_report 평가서를 실행, jobs 로 병렬, offline 기본 true), 납품 패키지(delivery-manifest.json: assessment/assessment.json 을 읽기만), CI 아티팩트(egovframe-assessment.json 또는 egovframe-delivery/ — 생성 CI 의 egovframe-supply-chain 아티팩트를 내려받은 폴더). 행: RTE 버전·세대, 전환 난이도·공급망·운영 준비 등급, 수동 전환 항목, 취약 의존성(OSV 조회한 평가서만)·노후 의존성, 보안약점 높음/중간, 공통컴포넌트 수, 평가일, 담당(ownerMap CSV). 분포(세대·등급별)와 '먼저 손댈 것'(여러 프로젝트에 걸친 취약 좌표·보안약점 규칙·운영 미달 규칙 Top N). previous(이전 portfolio.json)를 주면 프로젝트별 등급·취약 ID 변화와 빠진 프로젝트, sort·only(migration:C·supplyChain:D·operations:C·vulnerabilities>0·secure>0·era:4.x·failed)로 정렬·필터. 실패한 입력은 행에 사유. outputDir 를 주면 portfolio.md·portfolio.csv(UTF-8 BOM, 엑셀)·portfolio.json 을 새 디렉터리에 씁니다(프로젝트는 바꾸지 않음).

공식 egovframe-common-components 태그·commit·아카이브 무결성을 검증하고, 고정 카탈로그 대비 upstream 변경과 sec.security 보안 패키지를 점검합니다.

공식 프로젝트 템플릿 통합 카탈로그(Initializr·MCP·Development)를 upstream 과 대조해 추가·삭제·변경과 MCP 커버리지 격차를 보고하고, 동봉한 5.x 전환 규칙·의존성 기준 카탈로그의 drift(egovframe-runtime·공통컴포넌트의 새 태그, 공식 parent 의 새 버전, 고정 pom sha256 변화)도 함께 보고합니다. 파일은 고치지 않습니다.

eGovFrame 프로젝트의 테스트를 실제로 실행하고 JUnit XML 리포트(surefire/gradle)를 읽어 결과를 구조화합니다. 스위트별 통과·실패·오류·건너뜀 수와, 실패 케이스의 메시지·예외 타입·테스트 파일/라인을 반환합니다. testFilter로 특정 클래스/메서드만 실행할 수 있고, 원격 저장소 일시 장애는 다시 실행합니다(retryTransient). dryRun으로 실행 예정 명령을 미리볼 수 있습니다. (build_egovframe_project 의 테스트 후속)

매니페스트에 기록된 설치 공통컴포넌트를 카탈로그 고정 태그(이 도구 버전이 아는 최신)로 3-way 갱신합니다 — 기준은 매니페스트에 적힌 설치 태그, 파일마다 불변/갱신/추가/사용자수정(보존)/충돌/upstream삭제 로 분류. 사용자가 수정한 파일은 force 없이는 보존하며, dryRun(기본)으로 변경 계획을 먼저 확인합니다. 덮어쓰기 전 upgrade-backup/에 백업하고, 하드 충돌 시 아무것도 쓰지 않고 거부합니다. v1.12: reapply=true 면 충돌 파일(사용자 수정 + upstream 변경)을 기준·현재·목표 3-way(git merge-file)로 합쳐 충돌 없는 것만 적용하고, 합치지 못한 파일만 거부(force 로 덮어쓰기)합니다 — 파일에 충돌 표식을 넣지 않습니다. verify=true 면 적용 뒤 compile 해 합친 파일에서 오류가 나면 그 파일을 upstream 본으로 되돌립니다.

조립된 프로젝트의 무결성을 진단합니다: 설치 매니페스트 기준 파일 존재 확인, Globals.DbType과 복사된 DB 스크립트 일치 확인, 매퍼·DAO 정합성(v1.19 — DAO 의 문자열 ID·Mapper 인터페이스 메서드가 가리키는 문장이 XML 에 없는 곳과 비슷한 이름 후보, DB 별 매퍼 사이 문장 차이, include·resultMap 대상 없음, id 중복. 컴파일·기동으로 잡히지 않고 그 화면을 누를 때 실패하는 결함).

프로젝트를 바꾸지 않고 실제로 띄워 기동되는지 확인합니다 — 컴파일로 잡히지 않는 빈 생성 실패·설정 파일 경로·DB 접속·JDBC 드라이버·MyBatis 매퍼 XML 오류를 찾습니다. Spring Boot 는 mvn spring-boot:run / gradle bootRun 에 빈 포트를 --server.port 로 주고, Classic war 는 패키징한 war 를 캐시의 고정 버전 Tomcat 10.1(Servlet 6.1 이상이면 11.0, sha256 검증, 사내 미러 EGOVFRAME_MAVEN_MIRROR 우선)에 ROOT 로 두고 임시 CATALINA_BASE 로 띄웁니다(tomcatHome 으로 설치된 Tomcat 지정 가능). 로그의 기동 완료 문구 뒤 HTTP(기본 /, actuator 가 있으면 /actuator/health)로 확인해 5xx 가 아니면 기동으로 보고, 실패면 Spring 원인 사슬을 구조화합니다 — 종류(빌드 실패·원격 저장소 장애·포트 사용 중·JDBC 드라이버 없음·DB 접속 실패·매퍼 XML 오류·설정 누락·javax 네임스페이스·빈 생성 실패·HTTP 오류·시간 초과), 실제로 실패한 빈 이름, 관련 설정 자원(배포 사본 경로를 프로젝트 원본 경로로)·줄, JDBC URL·드라이버, 종류별 처방(드라이버 좌표, prepare_egovframe_database, migrate_egovframe_project 등)과 로그 끝부분. 끝나면 프로세스 트리를 끝냅니다. 화면 기능 테스트·운영 WAS(JEUS 등) 기동은 하지 않습니다.