(#81) backend verification과 AGENTS entrypoint 정렬

* chore: 백엔드 레거시 검증 자산 제거

- legacy verification Gradle task와 CI workflow 제거
- OpenAPI tracked 문서와 verification 전용 테스트 제거
- harness 재구성을 위한 clean baseline 정리

* ci: 백엔드 최소 검증 게이트 복구

* docs: 백엔드 엔트리포인트를 AGENTS로 정리

- backend root AGENTS.md 추가
- README overview-only 원칙과 verification/bootstrap discovery order 명시
- local skill 부재 시 repo-local fallback source 정리

* ci: 백엔드 PR 리뷰 피드백을 반영

- CI와 deploy verify 단계에 packaging build 추가
- 수동 배포를 main과 release tag ref로 제한
- AGENTS verification 문구를 실제 task wiring에 맞게 수정

---------

Co-authored-by: 백효석 <202580031@jei.com>

Author: alexization

.github/workflows/ci.yml

@@ -11,10 +11,29 @@ on:
       - develop
 
 jobs:
-  placeholder:
-    name: CI Placeholder
+  verify:
+    name: Unit and Integration Verification
     runs-on: ubuntu-latest
 
     steps:
-      - name: Verification reset notice
-        run: echo "Backend automated test verification is temporarily disabled."
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Java 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+          cache: 'gradle'
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Run unit tests
+        run: ./gradlew test
+
+      - name: Run integration tests
+        run: ./gradlew integrationTest
+
+      - name: Run packaging build
+        run: ./gradlew build -x test

.github/workflows/deploy.yml

@@ -12,9 +12,37 @@ env:
   IMAGE_NAME: git-ranker
 
 jobs:
+  verify:
+    name: Pre-deploy Verification
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Java 21
+        uses: actions/setup-java@v4
+        with:
+          java-version: '21'
+          distribution: 'temurin'
+          cache: 'gradle'
+
+      - name: Grant execute permission for gradlew
+        run: chmod +x gradlew
+
+      - name: Run unit tests
+        run: ./gradlew test
+
+      - name: Run integration tests
+        run: ./gradlew integrationTest
+
+      - name: Run packaging build
+        run: ./gradlew build -x test
+
   docker:
     name: Build & Push Docker Image
     runs-on: ubuntu-latest
+    needs: verify
 
     steps:
       - name: Checkout code
@@ -54,7 +82,7 @@ jobs:
     runs-on: ubuntu-latest
     needs: docker
 
-    if: github.ref == 'refs/heads/main' || github.event_name == 'workflow_dispatch'
+    if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
 
     steps:
       - name: Deploy via SSH

AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md
+
+`git-ranker`는 Git Ranker의 backend API 서버 저장소다. workflow repo는 orchestration만 소유하고, backend 구현과 verification/deploy entrypoint의 canonical source는 이 저장소가 직접 소유한다.
+
+## 시작 순서
+
+1. `README.md`에서 프로젝트 목적과 high-level overview를 확인한다.
+2. `build.gradle`, `settings.gradle`에서 모듈 구조, 의존성, verification task를 확인한다.
+3. `.github/workflows/ci.yml`, `.github/workflows/deploy.yml`에서 CI verification lane과 pre-deploy gate를 확인한다.
+4. `src/test/java/`에서 current verification slice를 본다.
+   - `*IT.java`는 Testcontainers 기반 integration lane이다.
+5. `src/main/java/`, `src/main/resources/`에서 실제 구현과 runtime config를 읽는다.
+
+## Source Of Truth
+
+- repo overview: `README.md`
+- build and verification entrypoint: `build.gradle`
+- CI / deploy gate: `.github/workflows/ci.yml`, `.github/workflows/deploy.yml`
+- backend behavior and contracts: `src/main/java/`, `src/test/java/`
+- runtime container surface: `Dockerfile`, `docker-compose.yml`
+
+## 운영 원칙
+
+- backend 구현 세부사항은 workflow repo 문서가 아니라 이 저장소의 문서, 설정, 코드, 테스트가 canonical source다.
+- root `README.md`는 개요만 유지한다. concrete bootstrap, verification, entrypoint 설명은 `AGENTS.md`와 named entry docs가 맡는다.
+- 현재 verification baseline command set은 `./gradlew test`, `./gradlew integrationTest`, packaging check `./gradlew build`다.
+- `./gradlew build`만으로는 `integrationTest`가 실행되지 않는다. CI/deploy gate는 이 순서를 명시적으로 호출하고, workflow에서는 마지막 packaging check를 `./gradlew build -x test`로 실행해 중복 unit test를 피한다.
+- `integrationTest`는 Docker/Testcontainers 전제를 가진다. 로컬 환경에서 Docker가 없으면 CI evidence와 함께 해석한다.
+- verification lane이나 deploy gate를 바꾸면 `build.gradle`, workflow YAML, `AGENTS.md`를 함께 맞춘다.
+- 현재 repo-local `.codex/skills/`는 없다. 별도 skill이 없을 때는 이 문서와 nearest code/test를 먼저 읽고 진행한다.

build.gradle

@@ -46,8 +46,41 @@ dependencies {
 	runtimeOnly 'io.micrometer:micrometer-registry-prometheus'
 	runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.12.3'
 	runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.12.3'
+
+	testImplementation 'io.projectreactor:reactor-test'
+	testImplementation 'org.springframework.security:spring-security-test'
+	testImplementation 'org.springframework.batch:spring-batch-test'
+	testImplementation 'org.springframework.boot:spring-boot-starter-test'
+	testImplementation 'org.springframework.boot:spring-boot-testcontainers'
+	testImplementation 'org.testcontainers:junit-jupiter'
+	testImplementation 'org.testcontainers:mysql'
+
+	testRuntimeOnly 'com.h2database:h2'
+	testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
+}
+
+// 단위 테스트: *IT.java 제외 (Docker 불필요)
+tasks.named('test') {
+	useJUnitPlatform()
+	exclude '**/*IT.class'
 }
 
+// 통합 테스트: Testcontainers 기반 *IT.java만 별도 lane에서 실행
+// check 라이프사이클에는 연결하지 않고 CI/deploy verification이 명시적으로 호출한다.
+tasks.register('integrationTest', Test) {
+	group = 'verification'
+	description = 'Runs Testcontainers-backed integration tests.'
+	useJUnitPlatform()
+	include '**/*IT.class'
+
+	mustRunAfter tasks.named('test')
+
+	testClassesDirs = sourceSets.test.output.classesDirs
+	classpath = sourceSets.test.runtimeClasspath
+
+	// Docker 29+는 최소 API 1.44를 요구하지만 docker-java 3.4.0은 기본값 1.32로 요청함
+	systemProperty 'api.version', '1.44'
+}
 tasks.named('processResources') {
 	filteringCharset = 'UTF-8'
 	filesMatching('static/swagger-ui/index.html') {