# 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별로 정렬
    }
  }
]);
```