빌드와 의존성 위생

이 페이지는 Lumie의 빌드와 의존성 위생에 대한 영어 기준 원본 reference 문서의 한국어 미러입니다. 저장소와 현재 활성 GitHub Actions 워크플로가 오늘 실제로 무엇을 강제하는지, 그리고 운영자가 덮어쓰지 말아야 할 계약 드리프트가 무엇인지 문서화합니다.

소스 경로

경로	역할
lumie-backend/build.gradle.kts	루트 Gradle 빌드, 공통 검증 연결, license 게이트, 백엔드 lint sweep
lumie-backend/gradle/libs.versions.toml	Spring Boot 3.4.13을 포함한 백엔드 버전 카탈로그
lumie-backend/config/allowed-licenses.json	의존성 license 검사에 사용하는 백엔드 허용 목록
lumie-backend/app/src/main/resources/application-dev.yml	dev 전용 Flyway seed 위치 override
lumie-frontend/package.json	프론트엔드 Node engine, 스크립트, 운영 의존성 license 게이트
lumie-worker/pyproject.toml	워커 uv workspace 멤버와 공통 Ruff, mypy 설정
lumie-worker/Makefile	uv.lock에서 커밋된 requirements.txt 파일로 내보내는 계약
lumie-worker/services/*/Dockerfile	여전히 내보낸 requirements.txt에서 설치하는 런타임 패키징 경로
lumie-worker/Tiltfile	서비스 requirements.txt를 다시 설치하는 dev live-update 경로
lumie-backend/.github/workflows/ci.yml	활성 백엔드 check, ARM 이미지 빌드, Zot 푸시, 이미지 태그 write-back 워크플로
lumie-frontend/.github/workflows/ci.yml	활성 프론트엔드 테스트, typecheck, lint, OpenAPI client 드리프트, audit, 이미지 빌드, 이미지 태그 write-back 워크플로
lumie-worker/.github/workflows/ci.yml	활성 워커 lint, requirements 드리프트, pytest, 이미지 빌드, 이미지 태그 write-back 워크플로
lumie-infra/applications/tekton/ci-cd/**	재활성화 경로로 남겨 둔 비활성 Tekton task와 pipeline 매니페스트
.github/tilt-up.sh	프론트엔드는 로컬, 나머지는 클러스터를 쓰는 하이브리드 dev 루프의 워크스페이스 진입점

저장소별 현재 상태

영역	활성 빌드 계약	의존성 위생 계약	눈여겨볼 제한 또는 드리프트
lumie-backend	check, integrationTest, jacocoTestReport가 연결된 Gradle Kotlin DSL 멀티모듈 빌드	루트 check가 license 허용 목록 검증과 scripts/lumie-lint/sweep.sh에 의존	Error Prone은 경고 전용이며, jacocoTestCoverageVerification은 정의되어 있지만 check에 연결되어 있지 않음
lumie-frontend	커밋된 lockfile, test:unit, tsc --noEmit, lint, npm audit, Orval 생성 client 드리프트 검사를 포함한 npm 기반 워크플로	license:check가 운영 의존성 SPDX 허용 목록을 로컬에서 강제하지만, 현재 활성 워크플로는 이를 아직 실행하지 않음	package.json은 Node >=24.18.0 <25를 요구하지만, 현재 워크플로는 여전히 Node 22를 설정
lumie-worker	루트 uv workspace, 서비스별 pyproject.toml, 내보낸 requirements.txt, GitHub Actions의 서비스 pytest 루프	활성 워크플로가 Lumie lint, Ruff, mypy, GPL 또는 AGPL 거부, requirements 드리프트 검사를 실행	활성 워크플로는 analysis, grading, report, chatbot을 다루며, temp-omr-grading은 이미지를 빌드하지만 공통 Python 테스트 루프에는 포함되지 않음
Workspace dev loop	.github/tilt-up.sh가 클러스터 터널을 열고 공용 워크스페이스에서 Tilt를 시작	백엔드 application-dev.yml이 classpath:db/seed를 추가해 dev seed 데이터를 백엔드 프로필에 포함	오래된 감사 노트와 달리 현재 저장소 루트에는 커밋된 .env.example 파일이 없음

백엔드 계약

lumie-backend/build.gradle.kts가 백엔드 강제 지점입니다.

대표 발췌:

tasks.named("check") {
    dependsOn("checkLicense")
}

tasks.named("check") {
    dependsOn("lumieLint")
}

이 파일이 증명하는 현재 규칙:

• Java 툴체인은 버전 카탈로그를 통해 21로 고정됩니다.
• test는 기본적으로 @Tag("integration")을 제외합니다.
• integrationTest가 명시적인 Testcontainers 경로입니다.
• spotlessCheck는 check의 일부입니다.
• license 강제는 권고가 아니라 차단 규칙입니다.
• JaCoCo 최소 커버리지 0.30은 존재하지만 check에 포함되지는 않습니다.

프론트엔드 계약

lumie-frontend/package.json이 로컬 도구의 기준 원본입니다.

• Node engine: >=24.18.0 <25
• lint: ESLint와 scripts/lumie-lint/sweep.sh frontend --paths '*'
• test:unit: Vitest
• test:e2e:*: API, flow, UI, SSR, 환경별 실행을 위한 Playwright 스위트
• license:check: license-checker-rseidelsohn을 통한 운영 의존성 whitelist

현재 GitHub Actions 워크플로는 로컬 스크립트 표면보다 더 많은 검사를 합니다.

• npm ci --prefer-offline
• npx orval --config orval.config.ts
• src/entities/*/api/generated.ts에 대한 git diff 검사
• npx tsc --noEmit
• npm run lint
• npm audit --audit-level=high

드리프트는 그대로 문서화해야 합니다. 저장소는 Node 24 engine을 선언하지만, 현재 워크플로는 여전히 actions/setup-node에서 node-version: "22"를 사용합니다.

워커 계약

lumie-worker는 uv를 의존성 기준 원본으로 사용하지만, 런타임 패키징은 여전히 내보낸 requirements.txt에서 설치합니다.

lumie-worker/Makefile의 대표 발췌:

EXPORT = $(UV) export --frozen --no-dev --no-emit-project --no-header

regen-requirements:
	$(EXPORT) --package grading-svc  --output-file services/grading/requirements.txt
	$(EXPORT) --package report-svc   --output-file services/report/requirements.txt
	$(EXPORT) --package analysis-svc --output-file services/analysis/requirements.txt
	$(EXPORT) --package chatbot-svc  --output-file services/chatbot/requirements.txt

실질적인 의미는 다음과 같습니다.

• uv.lock이 workspace 잠금 기준 원본입니다.
• 커밋된 requirements.txt 파일은 Docker와 Tilt를 위한 생성 산출물입니다.
• 서비스 Dockerfile은 이 내보낸 requirements 파일을 복사해 설치합니다.
• 활성 워크플로는 uv export --frozen 결과와 커밋된 파일 사이의 드리프트를 거부합니다.

활성 CI 적용 범위는 의도적으로 서비스 중심입니다.

• requirements 드리프트와 pytest 루프는 analysis, grading, report, chatbot을 다룹니다
• 이미지 매트릭스는 이 네 서비스와 temp-omr-grading을 빌드합니다
• temp-omr-grading은 임시 서비스 형태이기 때문에 공통 Ruff, mypy, requirements 드리프트, pytest 루프 바깥에 남아 있습니다

CI 게이트 운영 자세

현재 활성 CI 게이트는 GitHub Actions 기반입니다.

• backend build-push는 Gradle check를 기다립니다
• frontend build-push는 install, unit test, typecheck, lint, OpenAPI client 드리프트, high-severity audit를 기다립니다
• worker build-push는 Lumie lint, Ruff, format check, mypy, license check, requirements 드리프트, 서비스 pytest 루프를 기다립니다

세 활성 워크플로는 모두 ARM64 이미지를 빌드하고, Zot에 short-SHA와 main 태그를 푸시하며, main에서는 short-SHA 태그를 Lumie-Edu/lumie-image-tags에 다시 기록합니다.

Tekton은 다릅니다. 체크인된 Tekton task와 pipeline은 여전히 lumie-infra/applications/tekton/ci-cd/** 아래에 있고, INFORMATIONAL=true 같은 advisory 동작을 지원하는 task도 있지만, Tekton Argo CD 애플리케이션은 lumie-infra/applications/kustomization.yaml에서 비활성화되어 있습니다. Tekton 드리프트는 활성 CI 동작이 아니라 재활성화 위험으로 취급해야 합니다.

CI/CD와 Tekton에서 배포 전달 경로와 비활성 Tekton 경계를 확인하세요.

Dev 부트스트랩 메모

워크스페이스 dev 루프는 여전히 루트 AGENTS.md의 하이브리드 모델입니다.

• 프론트엔드는 로컬
• 백엔드, 워커, 상태 저장 서비스는 dev 클러스터
• .github/tilt-up.sh가 지원되는 진입점

백엔드 dev seed 데이터는 실제 코드에 연결된 상태입니다.

• application-dev.yml이 classpath:db/seed를 추가합니다
• R__dev_seed.sql은 INSERT ... ON CONFLICT DO NOTHING을 통해 안전하게 다시 실행됩니다

저장소가 오늘 실제로 제공하는 것보다 더 강한 환경 부트스트랩 보장을 주장하면 안 됩니다. 현재 트리 기준으로 저장소 루트에는 커밋된 .env.example 파일이 없습니다.

검증

가장 좁은 관련 읽기 전용 또는 검증 중심 명령을 사용하세요.

cd /Users/bluemayne/Projects/Lumie/lumie-backend
./gradlew check
./gradlew integrationTest
./gradlew jacocoTestCoverageVerification

cd /Users/bluemayne/Projects/Lumie/lumie-frontend
npm ci
npm run test:unit
npm run lint
npm run license:check

cd /Users/bluemayne/Projects/Lumie/lumie-worker
uv lock --check
uv run pytest services/analysis/tests services/grading/tests services/report/tests
uv export --frozen --no-dev --no-emit-project --no-header --package grading-svc | diff -u services/grading/requirements.txt -

cd /Users/bluemayne/Projects/Lumie
rg -n "actions/setup-node|orval|npm audit|uv export|docker/build-push-action|image-values" \
  lumie-backend/.github/workflows/ci.yml \
  lumie-frontend/.github/workflows/ci.yml \
  lumie-worker/.github/workflows/ci.yml

성공은 저장소별 검사가 통과하고, 생성된 의존성 내보내기가 동기화된 상태를 유지하며, 활성 GitHub Actions 워크플로가 문서화한 강제 규칙과 계속 일치함을 뜻합니다.

현재 공백

• 릴리스 태깅과 자동 릴리스 프로세스는 검토한 저장소에서 체크인된 빌드 게이트로 인코딩되어 있지 않습니다.
• 백엔드 커버리지 강제는 task로 존재하지만 기본 백엔드 check 그래프에는 들어 있지 않습니다.
• 프론트엔드 GitHub Actions 런타임과 선언된 Node engine이 서로 맞지 않습니다.
• temp-omr-grading은 워커 CI가 이미지를 빌드하지만 공통 워커 테스트와 의존성 드리프트 루프 바깥에 남아 있습니다.
• 커밋된 .env.example 파일이 있다는 오래된 감사 주장은 현재 저장소 트리와 일치하지 않습니다.