Agent 2.0 exdev 서버 배포 스택

- server-dev start/stop/deploy 및 Gitea push 자동 배포 - local-dev 로컬 개발 환경 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-21 22:57:30 +09:00
commit 4b86b2a660
344 changed files with 45787 additions and 0 deletions
@@ -0,0 +1,102 @@
+# chatbotApi 설명서
+
+> 해당 문서는 md(Markdown) 방식으로 작성되었기 때문에 마크다운 뷰어 기능이있는 편집기(vscode 등)에서 보는것을 추천드립니다.(vscode 사용 시 문서 열고 Ctrl + Shift + V)
+
+
+## 1. 개요
+챗봇에서 데이터 조회를 위한 api 서비스(backend, was). intent 정책(SSOT `intent-definitions.yml`)·검증·정규화와 도메인 데이터 조회(Oracle Handler / WEB 위임)를 담당합니다.
+
+### 1.1 시스템 구성 흐름 (WAS 역할)
+
+```mermaid
+flowchart TD
+    RAG[exAiChatBot AgentService] --> TE[AgentToolController /api/v1/tools/*]
+
+    POL[intent-definitions.yml + validator/normalizer]
+    TE --> POL
+    POL --> OWN{fetchOwner}
+    OWN -->|WAS| ORA[IntentHandler → Oracle/TROAD]
+    OWN -->|WEB| SKI[KakaoSkillToolClient → Skill /internal/tools/data-portal]
+    ORA --> FMT[LlmDomainDataFormatter]
+    SKI --> FMT
+    FMT --> OUT([domainData + uiType])
+```
+
+| 진입 | 사용 모드 | 설명 |
+|------|-----------|------|
+| `GET /api/v1/tools/definitions` | Agent | YAML → OpenAI function schema (RAG tool 목록) |
+| `POST /api/v1/tools/execute` | Agent | domain tool 실행 (`fetchOwner` 분기: WAS Oracle / WEB Skill 역호출) |
+
+- **정책 SSOT:** `src/main/resources/intent-definitions.yml` (`fetchOwner`/`uiType`/`requiredParams`/`clarification`).
+- **핵심 원칙:** LLM은 intent·params만 결정, `fetchOwner`/`uiType`/`needsClarification`은 WAS+YAML+validator가 결정.
+- 전체 구조: [`../SYSTEM_ARCHITECTURE.md`](../SYSTEM_ARCHITECTURE.md) · Agent tool API 상세: [`../docs/AGENT_ARCHITECTURE.md`](../docs/AGENT_ARCHITECTURE.md) · RAG API: [`RAG_API_IMPLEMENTATION.md`](RAG_API_IMPLEMENTATION.md)
+
+
+## 2. 프로그램 관련 정보
+서비스 기동 서버 : 172.16.180.130(통합정산개발#1)
+* Java version : 8(JDK 1.8)
+* 서비스 기동 시점 : 상시
+* 연계DB : TROAD(교통정보, Oracle), chatbot(MongoDB) 
+* 사용 계정 : song
+* 서비스 홈 디렉토리 : /home/song/bin/chatbotApi
+* 서비스 파일 : chatbotApi-0.0.1-SNAPSHOT.jar
+* 서비스 설정 파일(config) : application.yml, logback-spring.xml
+* 서비스 로그 파일(logs) : chatbotApi.log
+* 서비스 시작 명령어(서비스 홈 디렉토리에서 수행해야한다.)
+
+``` bash
+./start.sh start   ## 백그라운드(실운영) 기동 명령어, 평시에는 해당 명령어를 사용한다.
+./start.sh starta  ## 포그라운드 기동 명령어, 에러 탐색 및 모니터링시 활용
+```
+
+## 3. 기타 주의 사항
+> 해당 서비스에는 교통정보 관련 API만 개발 되어있다. 향후에는 미납 조회 등 모든 서비스를 구현하면 좋을듯. (현재는 DMZ존에 위치한 챗봇 WEB서버(128.200.100.61)에 대부분의 조회 서비스가 운영되고있다. 별로 좋지않은 구조라 생각된다.)
+
+> [ASIS] WEB ↔ DB,  [TOBE] WEB ↔ WAS ↔ DB) 
+
+## ※ API 일별 사용 건수 조회 Mongo쿼리
+```javascript
+db.api_use_log.aggregate([
+  {
+    $group: {
+      _id: {
+        $substr: ["$request_time", 0, 10]  // 'yyyy-MM-dd' 부분만 추출
+      },
+      count: { $sum: 1 } // 각 날짜별로 문서 수를 계산
+    }
+  },
+  {
+    $sort: { "_id": 1 } // 날짜별로 정렬
+  }
+]);
+```
+
+## ※ API apikey 및 일별 사용 건수 조회 Mongo쿼리
+```javascript
+db.api_use_log.aggregate([
+  {
+    $addFields: {
+      // 'yyyy-MM-dd' 형식으로 날짜 부분만 추출하여 새 필드에 저장
+      "dateOnly": {
+        $substr: ["$request_time", 0, 10] // '2023-11-11' 부분만 추출
+      }
+    }
+  },
+  {
+    $group: {
+      // api_key와 추출된 날짜를 기준으로 그룹화
+      _id: {
+        api_key: "$api_key",
+        date: "$dateOnly"
+      },
+      count: { $sum: 1 } // 각 api_key와 날짜별로 문서 수를 계산
+    }
+  },
+  {
+    $sort: {
+      "_id.date": 1, // 날짜별로 정렬
+      "_id.api_key": 1 // api_key별로 정렬
+    }
+  }
+]);
+```