landing_page/README.md

# 🌐 경북대학교 AI 에이전트 네트워크 연구실 (ANL) 공식 웹사이트

> **AI Agent Networking Laboratory (ANL), School of Computer Science and Engineering, Kyungpook National University**
> 
> 본 리포지토리는 경북대학교 컴퓨터학부 AI 에이전트 네트워크 연구실의 공식 웹사이트 및 데이터 관리 대시보드 시스템입니다.
> **Next.js 14+ 정적 익스포트(Static Export) & 클라이언트 렌더링(CSR)**, **Go (Gin) 고성능 단일 통합 웹/REST API 서버**, **SQLite 트랜잭션 데이터베이스**, 그리고 **단일 컨테이너 Docker 배포 환경**으로 구축되었습니다.

---

## 📌 1. 연구실 개요 및 핵심 연구 분야 (Lab Overview & Research Focus)

- **연구실명**: AI 에이전트 네트워크 연구실 (ANL / AI Agent Networking Laboratory)
- **소속**: 경북대학교 IT대학 컴퓨터학부
- **지도교수**: 고석주 교수 (Prof. Seok-Joo Koh / `sjkoh@knu.ac.kr`)
- **연구 패러다임**:
  - **Present & Future**: **MCP & SKILL**, **멀티에이전트 오케스트레이션 (HERDR, crewAI, LangGraph)**, **이종 에이전트 상호운용성 표준 (ACP, A2A)**, 및 **AIoT gRPC/QUIC 고성능 통신 백본**

---

## 💡 2. 핵심 연구 분야 (Core Research Areas)

### 🔌 1) AI Agent 기능 확장 프로토콜 (MCP & SKILL)
- **MCP (Model Context Protocol)**: Anthropic 제정 오픈 규격으로 도구, 데이터 리소스, 프롬프트 표준 인터페이스 연동
- **SKILL (자율 확장 도구 패키지)**: 실행 코드 + 도구 명세 + Few-shot이 결합된 모듈형 에이전트 기능 확장
- **CLI 자율 코딩 에이전트**: Claude Code, Antigravity CLI 등 터미널 기반 자율 소프트웨어 엔지니어링

### 🤖 2) 멀티 에이전트 협업 및 오케스트레이션 (Multi-Agent Orchestration)
- **이종 에이전트 교차 검증**: 서로 다른 LLM 모델(Planner, Creator, Reviewer) 간 비평/합의 루프로 무결성 확보
- **오케스트레이션 인프라 코어**:
  - **HERDR**: 가상 백그라운드 프로세스 격리 및 에이전트 세션 TUI 관제
  - **LangGraph & crewAI**: 상태 보존형 순환 그래프, 역할 기반 분업 및 예외 롤백 처리

### 🌐 3) 에이전트 상호운용성 개방형 표준 (Agent Interoperability: ACP & A2A)
- **ACP (Agent Communication Protocol)**: IBM Research 제정 서비스 발견 및 태스크 위임 오픈 표준
- **A2A (Agent-to-Agent Protocol)**: Google/Linux Foundation 주도 이종 에이전트 간 표준 메시지 교환 통신 표준
- **Agent Card (`/.well-known/agent-card.json`)**: 에이전트 역량(Capabilities) 및 보안 사양 표준 프로필

### ⚡ 4) 지능형 사물인터넷 (AIoT) & 고성능 백본 (AIoT & gRPC/QUIC)
- **AIoT 분산 자율 제어**: 센서 계층과 엣지 연산 계층 간 멀티 에이전트 분산 배치
- **gRPC & QUIC 양방향 스트리밍**: HTTP/2 & HTTP/3 기반 고속 바이너리 멀티모달 전송

---

## 🏗️ 3. 시스템 아키텍처 (System Architecture)

```mermaid
graph TD
    User["🌐 User / Browser"]
    Admin["👑 Admin User"]

    subgraph Docker_App ["Unified Single Container (anl-app:8080)"]
        subgraph Go_Gin_Server ["Go Gin Unified Server Engine"]
            Router["Static File Server & SPA Fallback (/web)"]
            APIRouter["REST API Router (/api/v1) & CORS"]
            AuthMW["RequireAdminToken Middleware"]
            Handlers["CRUD Handlers (Home, Members, Pubs, Lectures, Standards)"]
            Repo["Repository Layer & Transaction Order Normalizer"]
        end

        subgraph Static_Web ["Static Exported Frontend (/app/web)"]
            PublicPages["Public Pages (CSR + SSG Shell)<br/>/, /members, /publications, /lectures, /standardization"]
            AdminConsole["Admin Dashboard (/console)<br/>Research Projects, Areas, Members, Pubs, Lectures, Standards"]
            API_Client["Origin-Relative API Client (/api/v1)"]
        end

        subgraph Storage ["Persistent Storage (anl-sqlite-storage / ./volumes/data)"]
            SQLiteDB[("SQLite Database<br/>/app/data/anl.db")]
        end
    end

    User -->|HTTP :8080| Router
    Admin -->|Bearer Auth :8080| Router
    Router --> PublicPages
    Router --> AdminConsole
    PublicPages --> API_Client
    AdminConsole --> API_Client
    API_Client -->|Internal Route /api/v1| APIRouter
    APIRouter --> AuthMW
    AuthMW --> Handlers
    Handlers --> Repo
    Repo --> SQLiteDB
```

---

## 📁 4. 디렉터리 구조 (Directory Structure)

```
landing_page/
├── README.md                      # [본 문서] 종합 프로젝트 가이드 및 배포/운영 문서
├── docker-compose.yml             # 통합 단일 컨테이너 (anl-app) Compose 오케스트레이션
├── .env.example                   # 환경변수 설정 템플릿
│
├── backend/                       # ⚡ [통합 Go 백엔드 & 정적 웹 서빙 서버]
│   ├── cmd/                       # 진입점 (api: 통합 서버, seed: 시더, export-content)
│   ├── internal/                  # 비즈니스 로직 (handlers, repository, router, config, httpx)
│   ├── db/backup/                 # 💾 데이터베이스 백업 (anl.db 바이너리, anl_dump.sql 전체 덤프)
│   ├── seed/data/                 # 초기 원시 JSON 시드 데이터
│   ├── Dockerfile                 # 3단계 통합 Multi-stage Dockerfile (Node 빌드 + Go 빌드 + Alpine 런타임)
│   ├── Makefile                   # 빌드, 테스트, 포맷, 백업(make backup-db) 타겟
│   └── go.mod                     # Go 모듈 의존성 정의
│
├── refer_landing_page/            # 🚀 [Next.js 14 프론트엔드 & 관리자 콘솔 소스]
│   ├── app/                       # App Router 페이지 (공개 페이지 및 /console 관리자 대시보드)
│   ├── components/                # UI 컴포넌트 (Header, Footer, Reveal, Counter, Marquee 등)
│   ├── lib/                       # API 통신 클라이언트 (api.ts: 조회, adminApi.ts: CRUD)
│   ├── docs/                      # 디자인 시스템 (DESIGN.md: Issue 01 에디토리얼 스타일)
│   ├── scripts/                   # E2E 테스트 스위트 및 데이터 검증 러너
│   ├── next.config.js             # output: "export" 정적 익스포트 설정
│   └── package.json               # Next.js, React, Tailwind CSS 의존성
│
├── .agents/                       # 🤖 멀티 에이전트 오케스트레이션 스킬 & 룰셋 (MAM)
├── .mam/                          # ⚡ 에이전트 세션 DB 및 HERDR 격리 레지스트리
└── ISL-2026/                      # 📄 레거시 실측 원본 HTML/CSS 아카이브
```

---

## 🚀 5. Docker 컨테이너 배포 및 운영 가이드 (Production Deployment)

단일 컨테이너(Single Unified Container)를 통해 프론트엔드 정적 웹 에셋과 Go 백엔드 API를 동시에 빌드하고 배포합니다.

### 1) 저장소 클론 및 환경 설정
```bash
# 1. 저장소 클론
git clone <리포지토리_URL> landing_page
cd landing_page

# 2. 환경변수 파일 생성
cp .env.example .env

# (선택) .env 파일에서 관리자 토큰(ADMIN_TOKEN) 및 포트(APP_PORT) 설정
```

### 2) 컨테이너 이미지 빌드
```bash
# 통합 단일 컨테이너 (anl-app) 빌드
docker compose build

# (선택) 캐시 없이 전체 재빌드 시
docker compose build --no-cache
```

### 3) 서비스 백그라운드 배포 및 실행
```bash
# 1. 컨테이너 백그라운드 실행
docker compose up -d

# 2. 실행 상태 및 헬스체크 확인 (anl-app)
docker compose ps

# 3. 실시간 로그 모니터링
docker compose logs -f
```

### 4) 서비스 접속 URL
- **🌐 공식 홈페이지**: [`http://localhost:8080`](http://localhost:8080)
- **👑 관리자 대시보드**: [`http://localhost:8080/console`](http://localhost:8080/console) (로그인 토큰: `.env`에 설정된 `ADMIN_TOKEN`)
- **⚡ 백엔드 REST API**: [`http://localhost:8080/api/v1`](http://localhost:8080/api/v1)
- **💓 API 헬스체크**: [`http://localhost:8080/api/v1/health`](http://localhost:8080/api/v1/health)

### 5) 📂 호스트 디렉터리 바인드 마운트 (`./volumes/data`)로 변경하는 방법
기본 명명된 볼륨 대신 호스트 로컬 폴더에 SQLite DB를 직접 마운트하여 관리하고 싶다면:

1. `docker-compose.yml`의 `anl-app` 볼륨 설정을 수정합니다:
   ```yaml
   services:
     anl-app:
       # ...
       volumes:
         - ./volumes/data:/app/data
   ```
2. 파일 맨 아래의 `volumes:` 섹션을 주석 처리하거나 제거합니다.
3. 호스트 디렉터리 생성 및 DB 배치:
   ```bash
   mkdir -p volumes/data
   cp backend/db/backup/anl.db volumes/data/anl.db
   ```
4. 컨테이너 재시작: `docker compose down && docker compose up -d`

### 6) 컨테이너 관리 및 중지
```bash
# 서비스 재시작
docker compose restart

# 서비스 중지 및 컨테이너 제거 (데이터베이스 볼륨은 안전하게 보존됨)
docker compose down

# (주의) 데이터베이스 볼륨까지 완전히 삭제하고 초기화할 때
docker compose down -v
```

---

## 🛠️ 6. 로컬 개발 및 실행 가이드 (Getting Started)

### 🅰️ Backend (Go REST API & Web Server) 개발 가이드
```bash
cd backend
cp .env.example .env

# 데이터베이스 시드 및 마이그레이션 실행
make migrate-seed

# 백엔드 서버 로컬 구동 (기본 포트: 8080)
go run ./cmd/api --db anl.db --admin-token dev_admin_secret_token_12345
```

### 🅱️ Frontend (Next.js 14) 개발 가이드
```bash
cd refer_landing_page

# 종속성 설치
npm install

# 개발 서버 실행 (Next.js dev 서버: http://localhost:3000)
npm run dev

# 정적 익스포트 빌드 검증 (out/ 디렉터리 생성)
npm run build
```

---

## 🧪 7. 품질 검증 및 E2E 테스트 스위트 (12 Quality Gates)

```bash
cd refer_landing_page
python3 scripts/run_e2e_tests.py
```
모든 12개 품질 게이트(Static Build Completeness, TypeScript, ESLint, SQLite Baseline, Live Unified Go Server Routes, DOM Content, Layout Architecture, WCAG Contrast 등)가 100% 무결하게 검증됩니다.