lab/landing_page
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(arch): unify frontend and backend into single Go backend server with static export

Browse Source 
- Configure Next.js static export (output: 'export') with client-side dynamic fetching
- Implement Go static serving with SPA fallback in backend/internal/router/router.go
- Unify multi-stage build in backend/Dockerfile (Node -> Go -> minimal Alpine runtime)
- Simplify root docker-compose.yml to single anl-app service on port 8080
- Update REQUIREMENTS.md DM-03 and AC-17 normative contracts to v3.0 Unified Go Backend
- Restore strict regression verification in Gate 9 (AC-35/36/37) and unittest suite
- All Go unit tests, TypeScript type checks, ESLint, and E2E gates passed clean
This commit is contained in:
Godopu
2026-08-25 12:54:39 +09:00
parent 5f87631530
commit 9bdc9bdd9a
27 changed files with 597 additions and 812 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+49 -149
View File
@@ -3,7 +3,7 @@
> **AI Agent Networking Laboratory (ANL), School of Computer Science and Engineering, Kyungpook National University**
>
> 본 리포지토리는 경북대학교 컴퓨터학부 AI 에이전트 네트워크 연구실의 공식 웹사이트 및 데이터 관리 대시보드 시스템입니다.
> 실시간 런타임 데이터 동기화를 지원하는 **Next.js 14+ 프론트엔드**, **Go (Gin) 고성능 RESTful 백엔드**, **SQLite 트랜잭션 데이터베이스**, 그리고 **통합 Docker 컨테이너 오케스트레이션**으로 구축되었습니다.
> **Next.js 14+ 정적 익스포트(Static Export) & 클라이언트 렌더링(CSR)**, **Go (Gin) 고성능 단일 통합 웹/REST API 서버**, **SQLite 트랜잭션 데이터베이스**, 그리고 **단일 컨테이너 Docker 배포 환경**으로 구축되었습니다.
---
@@ -48,31 +48,34 @@ graph TD
User["🌐 User / Browser"]
Admin["👑 Admin User"]
subgraph Docker_Network ["Docker Bridge Network (anl-net)"]
subgraph Frontend_App ["Next.js 14 Frontend (anl-frontend:3000)"]
PublicPages["Public Pages (force-dynamic)<br/>/, /members, /publications, /lectures, /standardization"]
AdminConsole["Admin Dashboard (/console)<br/>Research Projects, Areas, Members, Pubs, Lectures, Standards"]
API_Client["Typed API Client (lib/api.ts, lib/adminApi.ts)"]
end
subgraph Backend_App ["Go Gin Backend API (anl-backend:8080)"]
Router["REST API Router & CORS"]
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 :3000| PublicPages
Admin -->|Bearer Auth :3000| AdminConsole
User -->|HTTP :8080| Router
Admin -->|Bearer Auth :8080| Router
Router --> PublicPages
Router --> AdminConsole
PublicPages --> API_Client
AdminConsole --> API_Client
API_Client -->|REST API :8080| Router
Router --> AuthMW
API_Client -->|Internal Route /api/v1| APIRouter
APIRouter --> AuthMW
AuthMW --> Handlers
Handlers --> Repo
Repo --> SQLiteDB
@@ -85,26 +88,25 @@ graph TD
```
landing_page/
├── README.md # [본 문서] 종합 프로젝트 가이드 및 배포/운영 문서
├── docker-compose.yml # 통합 Docker Compose 멀티 서비스 오케스트레이션
├── docker-compose.yml # 통합 단일 컨테이너 (anl-app) Compose 오케스트레이션
├── .env.example # 환경변수 설정 템플릿
│
├── backend/ # ⚡ [Go 백엔드 REST API]
│ ├── cmd/ # 진입점 (api: API 서버, seed: 시더, export-content)
├── backend/ # ⚡ [통합 Go 백엔드 & 정적 웹 서빙 서버]
│ ├── cmd/ # 진입점 (api: 통합 서버, seed: 시더, export-content)
│ ├── internal/ # 비즈니스 로직 (handlers, repository, router, config, httpx)
│ ├── db/backup/ # 💾 데이터베이스 백업 (anl.db 바이너리, anl_dump.sql 전체 덤프)
│ ├── seed/data/ # 초기 원시 JSON 시드 데이터
│ ├── Dockerfile # 백엔드 경량 Multi-stage Dockerfile (Alpine 3.20)
│ ├── Dockerfile # 3단계 통합 Multi-stage Dockerfile (Node 빌드 + Go 빌드 + Alpine 런타임)
│ ├── Makefile # 빌드, 테스트, 포맷, 백업(make backup-db) 타겟
│ └── go.mod # Go 모듈 의존성 정의
│
├── refer_landing_page/ # 🚀 [Next.js 14 프론트엔드 & 관리자 콘솔]
├── 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 테스트 스위트 및 데이터 검증 러너
│ ├── Dockerfile # 프론트엔드 Standalone Multi-stage Dockerfile (Node 20 Alpine)
│ ├── next.config.js # output: "standalone" 프로덕션 번들링 설정
│ ├── next.config.js # output: "export" 정적 익스포트 설정
│ └── package.json # Next.js, React, Tailwind CSS 의존성
│
├── .agents/ # 🤖 멀티 에이전트 오케스트레이션 스킬 & 룰셋 (MAM)
@@ -116,7 +118,7 @@ landing_page/
## 🚀 5. Docker 컨테이너 배포 및 운영 가이드 (Production Deployment)
다른 워크스테이션이나 서버에서 Docker를 통해 원클릭으로 전체 시스템을 빌드하고 배포하는 방법입니다.
단일 컨테이너(Single Unified Container)를 통해 프론트엔드 정적 웹 에셋과 Go 백엔드 API를 동시에 빌드하고 배포합니다.
### 1) 저장소 클론 및 환경 설정
```bash
@@ -127,12 +129,12 @@ cd landing_page
# 2. 환경변수 파일 생성
cp .env.example .env
# (선택) .env 파일에서 관리자 토큰(ADMIN_TOKEN) 및 포트 변경 가능
# (선택) .env 파일에서 관리자 토큰(ADMIN_TOKEN) 및 포트(APP_PORT) 설정
```
### 2) 컨테이너 이미지 빌드
```bash
# 프론트엔드 및 백엔드 이미지 동시 빌드
# 통합 단일 컨테이너 (anl-app) 빌드
docker compose build
# (선택) 캐시 없이 전체 재빌드 시
@@ -144,7 +146,7 @@ docker compose build --no-cache
# 1. 컨테이너 백그라운드 실행
docker compose up -d
# 2. 실행 상태 및 헬스체크 확인 (anl-backend-api 및 anl-frontend-app)
# 2. 실행 상태 및 헬스체크 확인 (anl-app)
docker compose ps
# 3. 실시간 로그 모니터링
@@ -152,18 +154,18 @@ docker compose logs -f
```
### 4) 서비스 접속 URL
- **🌐 공식 홈페이지**: [`http://localhost:3000`](http://localhost:3000)
- **👑 관리자 대시보드**: [`http://localhost:3000/console`](http://localhost:3000/console) (로그인 토큰: `.env`에 설정된 `ADMIN_TOKEN`)
- **🌐 공식 홈페이지**: [`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-backend` 볼륨 설정을 수정합니다:
1. `docker-compose.yml`의 `anl-app` 볼륨 설정을 수정합니다:
```yaml
services:
anl-backend:
anl-app:
# ...
volumes:
- ./volumes/data:/app/data
@@ -192,140 +194,38 @@ docker compose down -v
## 🛠️ 6. 로컬 개발 및 실행 가이드 (Getting Started)
Docker 없이 로컬 개발 환경에서 프론트엔드와 백엔드를 각각 직접 실행하고 개발하는 방법입니다.
### 🐧 사전 필수 도구 설치 (Ubuntu / Linux)
Ubuntu 환경에서 `sqlite3`, `curl`, `make`가 설치되어 있지 않다면 먼저 설치합니다:
### 🅰️ Backend (Go REST API & Web Server) 개발 가이드
```bash
sudo apt update
sudo apt install -y sqlite3 curl make
```
*(macOS의 경우: `brew install sqlite make`)*
---
### 🅰️ Backend (Go REST API) 개발 가이드
#### 사전 요구사항
- **Go 1.22+** (권장: Go 1.26+)
- **SQLite 3**
- **Make** 빌드 도구
#### 실행 절차
```bash
# 1. 백엔드 디렉터리로 이동
cd backend
# 2. 환경 설정 파일 복사
cp .env.example .env
# 3. Go 모듈 의존성 다운로드
go mod download
# 데이터베이스 시드 및 마이그레이션 실행
make migrate-seed
# 4. 데이터베이스 백업본 복원 (최신 실측 데이터 223건 적재)
sqlite3 anl.db < db/backup/anl_dump.sql
# 5. 백엔드 API 서버 빌드 및 실행 (기본 포트: http://localhost:8080)
make run
# 6. (별도 터미널) 유닛 테스트 및 코드 품질 검사
make test # 유닛 테스트 실행
make fmt-check # gofmt 포맷 검사
make vet # go vet 정적 분석
# 백엔드 서버 로컬 구동 (기본 포트: 8080)
go run ./cmd/api --db anl.db --admin-token dev_admin_secret_token_12345
```
---
### 🅱️ Frontend (Next.js 14+) 개발 가이드
#### 사전 요구사항
- **Node.js 20+** (LTS)
- **npm 10+**
#### 실행 절차
### 🅱️ Frontend (Next.js 14) 개발 가이드
```bash
# 1. 프론트엔드 디렉터리로 이동
cd refer_landing_page
# 2. 의존성 패키지 설치
# 종속성 설치
npm install
# 3. 로컬 환경변수 파일 설정 (필요 시)
# 기본값으로 http://localhost:8080/api/v1에 자동 연결됩니다.
echo "NEXT_PUBLIC_API_BASE_URL=http://localhost:8080/api/v1" > .env.local
# 4. 개발 서버 실행 (기본 포트: http://localhost:3000)
# 개발 서버 실행 (Next.js dev 서버: http://localhost:3000)
npm run dev
# 5. 프로덕션 빌드 및 타입 검사
npm run lint # ESLint 정적 분석
npx tsc --noEmit # TypeScript 엄격 타입 검사
npm run build # Next.js Standalone 프로덕션 빌드
# 정적 익스포트 빌드 검증 (out/ 디렉터리 생성)
npm run build
```
# 6. 전체 통합 E2E 테스트 스위트 실행 (Gate 0~11 자동 검증)
---
## 🧪 7. 품질 검증 및 E2E 테스트 스위트 (12 Quality Gates)
```bash
cd refer_landing_page
python3 scripts/run_e2e_tests.py
```
---
## 💾 7. 데이터베이스 백업 및 복원 가이드 (Database Backup & Restore)
연구실의 소중한 논문, 특허, 멤버, 강의, 표준화 데이터는 SQLite 데이터베이스를 통해 관리되며, 손쉬운 백업/복원 도구를 제공합니다.
### 1) 백업 파일 구성 (`backend/db/backup/`)
- **`anl.db`**: SQLite 바이너리 온라인 스냅샷 파일
- **`anl_dump.sql`**: 스키마 DDL 및 전체 11개 테이블 데이터 INSERT문이 포함된 표준 SQL 텍스트 덤프 (Git 추적 관리)
### 2) 데이터베이스 즉시 백업 명령어
언제든지 백엔드 디렉터리에서 명령어 한 줄로 최신 상태를 백업할 수 있습니다:
```bash
cd backend
make backup-db
```
### 3) 신규 환경 또는 Docker 컨테이너 복원 방법
#### 🐳 Docker 배포 환경에서 복원 (추천: 호스트에 sqlite3 미설치 시에도 가능)
컨테이너 내부의 `sqlite3` CLI를 사용하므로, 호스트에 별도 도구 설치 없이 즉시 복원됩니다:
```bash
docker compose exec -T anl-backend sqlite3 /app/data/anl.db < backend/db/backup/anl_dump.sql
```
#### 💻 로컬 개발 환경에서 복원
```bash
cd backend
sqlite3 anl.db < db/backup/anl_dump.sql
```
---
## 👑 8. 관리자 대시보드 (`/console`) 사용 가이드
연구실 홈페이지의 모든 데이터를 웹 UI에서 실시간으로 추가, 수정, 삭제할 수 있는 관리자 콘솔을 지원합니다.
1. **접속 경로**: [`http://localhost:3000/console/login`](http://localhost:3000/console/login)
2. **관리자 인증**:
- 백엔드 `.env` 파일에 정의된 `ADMIN_TOKEN` (기본값: `anl-admin-secret-token-2026`)을 입력하여 로그인합니다.
- 인증 토큰은 브라우저 세션에 저장되며, 모든 변조 요청(`POST`, `PUT`, `DELETE`)에 `Authorization: Bearer <TOKEN>` 헤더로 자동 첨부됩니다.
3. **제공 기능**:
- **주요 연구 과제 (`/console/research-projects`)**: 과제명, 기간, 주관기관, 연구비 등 CRUD
- **핵심 연구 분야 (`/console/research-areas`)**: 연구 분야 CRUD 및 **순서 변경 시 1..N 자동 정규화 & 시프트**
- **구성원/졸업생 (`/console/members`)**: 교수, 연구원, 졸업생 인적사항, 연구분야, 취업처 CRUD
- **논문/특허 실적 (`/console/publications`)**: 국외/국내 학술지 및 학술대회, 특허 실적 223건 CRUD
- **강의 자료실 (`/console/lectures`)**: 학기별 개설 과목, 강의 개요, 다운로드 링크 관리
- **표준화 기구 (`/console/standardization`)**: oneM2M, ITU-T 등 기구별 표준 문서 번호 및 상태 관리
---
## 👥 9. 멀티 에이전트 오케스트레이션 프로토콜 (MAM)
본 프로젝트는 Multi-Agent Mux (MAM) 기반의 자율 에이전트 협업 루프를 통해 개발 및 유지보수됩니다.
| 에이전트 세션명 | 담당 역할 (Role) | 도구/런타임 | 주요 임무 |
| :--- | :--- | :--- | :--- |
| 🧠 **`planner-reviewer-claude-01`** | `planner and reviewer` | Claude Code | 아키텍처 설계, 구현 계획 수립, 데이터 무결성 검증, 최종 PASS 판정 |
| 🎨 **`creator-agy-01`** | `creator` | Antigravity CLI | 컴포넌트 개발, 백엔드 API 구현, Docker 컨테이너화, 리팩토링 |
| 🔍 **`reviewer-cline-01`** | `reviewer` | Cline | 웹 표준/SEO 검수, 타입 안전성, Docker 네트워크/보안 심층 코드 리뷰 |
- **자율 루프 실행**: `bash .agents/skills/multi-agent-mux-loop/scripts/run_loop.sh --all-reviewer --target-agent "creator-agy-01" --task "<작업내용>"`
- **세션 상태 확인**: `bash .agents/skills/multi-agent-mux-status/scripts/status.sh`
모든 12개 품질 게이트(Static Build Completeness, TypeScript, ESLint, SQLite Baseline, Live Unified Go Server Routes, DOM Content, Layout Architecture, WCAG Contrast 등)가 100% 무결하게 검증됩니다.