feat(backend,docker,docs): implement Go/Gin/SQLite REST API server, Docker containerization, and architecture specifications

- Implement standalone Go backend API server using Gin and pure-Go SQLite (modernc.org/sqlite) - Add 11-table schema DDL migrations (000001_init.up.sql) based on DATA_TABLE.md - Add seed data ingestion tool (cmd/seed) and static TypeScript content exporter (cmd/export-content) - Add configuration loader (internal/config) supporting environment variables and .env files (HOST, PORT, DB_PATH, GIN_MODE, CORS_ALLOW_ORIGINS, AUTO_MIGRATE) - Add lightweight multi-stage Dockerfile and docker-compose.yml with persistent SQLite volume - Add comprehensive architecture specification (ARCHITECTURE.md) and REST API interface specification (API_INTERFACE.md) - Harmonize frontend publications page to consume isHighlight flag from database-synced content
2026-08-24 17:34:51 +09:00
parent 75bf334fec
commit fb6881070c
53 changed files with 8432 additions and 488 deletions
@@ -0,0 +1,366 @@
+# AI Agent Networking Lab (ANL) — REST API Interface Specification
+
+This document defines the RESTful API endpoints, request parameters, response schemas, and data structures provided by the ANL Go/Gin backend server.
+
+---
+
+## 1. General API Conventions
+
+### 1.1 Base URL
+- **Local Development**: `http://localhost:8080/api/v1`
+- **Protocol**: HTTP/1.1 (JSON Content-Type: `application/json; charset=utf-8`)
+
+### 1.2 Standard Response Envelope
+
+All API endpoints strictly follow the uniform JSON response envelope structure.
+
+#### Success Response (`200 OK`)
+```json
+{
+  "data": <Payload Object | Array>
+}
+```
+
+#### Error Response (`4xx / 5xx`)
+```json
+{
+  "error": {
+    "message": "Human-readable error description"
+  }
+}
+```
+
+### 1.3 HTTP Status Codes
+| Status Code | Description |
+|---|---|
+| `200 OK` | The request succeeded and returned the requested data. |
+| `400 Bad Request` | Invalid query parameter (e.g., unsupported publication category). |
+| `404 Not Found` | The requested resource was not found. |
+| `500 Internal Server Error` | Unexpected server-side failure during database query or processing. |
+
+---
+
+## 2. API Endpoints Specification
+
+### 2.1 System & Health
+
+#### `GET /api/v1/health`
+Checks backend API service health and database availability.
+
+- **Response Payload**:
+```json
+{
+  "data": {
+    "service": "anl-backend-api",
+    "status": "ok"
+  }
+}
+```
+
+---
+
+## 2.2 Home & Overview
+
+#### `GET /api/v1/research-projects`
+Retrieves the list of all active research projects.
+
+- **Response Payload**:
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "slug": "iot-standards",
+      "title": "AIoT & AI-RAN",
+      "abstract": "AIoT & AI-RAN investigates agent-based IoT architectures in which autonomous AI agents are distributed across sensor, edge, and radio access layers. The project studies agent-to-agent coordination over high-performance transport (gRPC/QUIC) bridged with constrained edge protocols (MQTT/CoAP), targeting AI-RAN designs for distributed autonomous control.",
+      "keywords": [
+        "AIoT",
+        "agent-based IoT",
+        "AI-RAN",
+        "constrained edge protocols",
+        "distributed autonomous control"
+      ],
+      "organization": "National Research Foundation of Korea (NRF)",
+      "standards_org": "NRF",
+      "period": "2026 ~ Present",
+      "funder": null,
+      "created_at": "2026-08-24T16:47:14Z",
+      "updated_at": "2026-08-24T16:47:14Z"
+    }
+  ]
+}
+```
+
+#### `GET /api/v1/research-areas`
+Retrieves the list of 14 core research areas ordered by `display_order`.
+
+- **Response Payload**:
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "name_en": "Quick UDP Internet Connection (QUIC)",
+      "name_kr": null,
+      "display_order": 1
+    },
+    {
+      "id": 2,
+      "name_en": "QUIC-based Mobility and Multi-Streaming Support",
+      "name_kr": null,
+      "display_order": 2
+    }
+  ]
+}
+```
+
+#### `GET /api/v1/stats/summary`
+Retrieves aggregated top-level metrics for the homepage hero section.
+
+- **Response Payload**:
+```json
+{
+  "data": {
+    "intl_publications": 68,
+    "standardization_docs": 44,
+    "patents": 75
+  }
+}
+```
+
+---
+
+## 2.3 Members & Alumni
+
+#### `GET /api/v1/members`
+Retrieves all 16 active members (including the professor and graduate researchers) ordered by `display_order`.
+
+- **Response Payload**:
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "name_ko": "고석주",
+      "name_en": "Seok-Joo Koh",
+      "degree": "Professor",
+      "affiliation": "School of Computer Science and Engineering",
+      "email": "sjkoh@knu.ac.kr",
+      "is_advisor": true,
+      "display_order": 1,
+      "created_at": "2026-08-24T16:47:14Z"
+    },
+    {
+      "id": 2,
+      "name_ko": "김경호",
+      "name_en": "Kyeong-Ho Kim",
+      "degree": "PhDStudent",
+      "affiliation": null,
+      "email": null,
+      "is_advisor": false,
+      "display_order": 2,
+      "created_at": "2026-08-24T16:47:14Z"
+    }
+  ]
+}
+```
+
+#### `GET /api/v1/alumni`
+Retrieves all 60 alumni sorted chronologically by `graduated_at DESC`.
+
+- **Response Payload**:
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "name_ko": "도경진",
+      "name_en": "Gyeong-Jin Do",
+      "degree": "MS",
+      "graduated_at": "2024-02",
+      "major": "School of Electronic and Electrical Engineering",
+      "current_position": "LIG Nex1, Senior Researcher",
+      "created_at": "2026-08-24T16:47:14Z"
+    }
+  ]
+}
+```
+
+---
+
+## 2.4 Publications & Intellectual Property
+
+#### `GET /api/v1/publications`
+Retrieves list of academic publications. Supports filtering by publication category.
+
+- **Query Parameters**:
+  - `category` (optional, string): Filter by category. Allowed values: `intl-journal-conf`, `domestic-journal-conf`.
+- **Response Payload**:
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "category": "intl-journal-conf",
+      "title": "Globally Integrated Trust Authority (GITA) for Resource-Constrained Edge Devices in IoT and 6G",
+      "authors": "Seok-Joo Koh, ...",
+      "venue": "IEEE Transactions on Network and Service Management",
+      "volume": "Vol. 23, pp. 4490~4505, April 2026",
+      "published_at": "2026-04",
+      "kci": false,
+      "doi": "10.1109/TNSM.2026.10908861",
+      "is_highlight": true,
+      "created_at": "2026-08-24T16:47:14Z"
+    }
+  ]
+}
+```
+
+#### `GET /api/v1/publications/highlights`
+Retrieves the **5 designated top representative publications** (`WHERE is_highlight = 1`).
+
+- **Response Payload**:
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "category": "intl-journal-conf",
+      "title": "Globally Integrated Trust Authority (GITA) for Resource-Constrained Edge Devices in IoT and 6G",
+      "authors": "Seok-Joo Koh, ...",
+      "venue": "IEEE Transactions on Network and Service Management",
+      "volume": "Vol. 23, pp. 4490~4505, April 2026",
+      "published_at": "2026-04",
+      "kci": false,
+      "doi": "10.1109/TNSM.2026.10908861",
+      "is_highlight": true,
+      "created_at": "2026-08-24T16:47:14Z"
+    },
+    {
+      "id": 2,
+      "category": "intl-journal-conf",
+      "title": "Application Level Trust Authority (APPLETA) for Resource-Constrained Edge Devices in IoT and 6G",
+      "authors": "Seok-Joo Koh, ...",
+      "venue": "IEEE Transactions on Consumer Electronics",
+      "volume": "Vol. 71, pp. 1120~1135, Jan. 2026",
+      "published_at": "2026-01",
+      "kci": false,
+      "doi": "10.1109/TCE.2025.3524673",
+      "is_highlight": true,
+      "created_at": "2026-08-24T16:47:14Z"
+    }
+  ]
+}
+```
+
+#### `GET /api/v1/patents`
+Retrieves all 75 registered and pending patents sorted by `published_at DESC`.
+
+- **Response Payload**:
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "title": "다중 인터페이스 기반 QUIC 핸드오버 지원 장치 및 방법",
+      "inventors": "고석주, 김경호",
+      "application_no": "10-2024-0012345",
+      "application_at": "2024-01-15",
+      "registration_no": "10-2567890",
+      "registration_at": "2025-05-20",
+      "country": "KR",
+      "published_at": "2025-05-20",
+      "created_at": "2026-08-24T16:47:14Z"
+    }
+  ]
+}
+```
+
+---
+
+## 2.5 Lectures & Curriculum
+
+#### `GET /api/v1/semesters`
+Retrieves all 45 academic semesters with nested course lists, ordered by `year DESC` and `term` (Fall before Spring).
+
+- **Response Payload**:
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "year": 2026,
+      "term": "Spring",
+      "courses": [
+        {
+          "id": 1,
+          "semester_id": 1,
+          "code": "COMP0411",
+          "name_en": "Computer Networks",
+          "name_kr": null,
+          "note": "Undergraduate Core",
+          "display_order": 1
+        }
+      ]
+    },
+    {
+      "id": 2,
+      "year": 2025,
+      "term": "Fall",
+      "courses": [
+        {
+          "id": 2,
+          "semester_id": 2,
+          "code": "COMP0754",
+          "name_en": "Advanced Internet Protocol",
+          "name_kr": null,
+          "note": "Graduate Course",
+          "display_order": 1
+        }
+      ]
+    }
+  ]
+}
+```
+
+---
+
+## 2.6 Standardization
+
+#### `GET /api/v1/standards-bodies`
+Retrieves all 6 standardization bodies with 3-tier hierarchy (`Body → Project (WG) → Documents[]`).
+
+- **Response Payload**:
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "org": "IEC TC100",
+      "full_name": "International Electrotechnical Commission: Technical Committee 100",
+      "scope": "international",
+      "period": "2018 ~ Present",
+      "role": "Project Editor / Active Contributor",
+      "display_order": 1,
+      "projects": [
+        {
+          "wg": "WG 12",
+          "name": "MCM: Multilateral and Collaborative Metaverse",
+          "documents": [
+            {
+              "id": 1,
+              "body_id": 1,
+              "wg": "WG 12",
+              "project_name": "MCM: Multilateral and Collaborative Metaverse",
+              "title": "Conceptual model for multilateral and collaborative metaverse systems",
+              "doc_ref": "IEC 63430 ED1",
+              "status": "IS",
+              "published_at": "2026-03"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```