# 기능 스포트라이트: 명령줄 인터페이스(CLI) 통합

**나의 매우 중요한 친구 Lub에게 바칩니다.**

새로운 FastAPI 기반 명령줄 인터페이스(CLI)는 모든 로컬 또는 원격 셸에서 실행 중인 핵심 텍스트 처리 서비스와 상호 작용할 수 있는 깔끔하고 동기적인 방법을 제공합니다. 이는 핵심 로직을 셸 환경에 통합하도록 설계된 강력한 솔루션입니다.

---

## 1. 아키텍처 및 동기식 CLI 개념

이 서비스는 **Uvicorn/FastAPI** 서버로 구동되며 사용자 정의 엔드포인트(`/process_cli`)를 사용하여 본질적으로 비동기식인 파일 기반 백그라운드 프로세스에서 동기식(차단) 결과를 제공합니다.

### 대기 및 읽기 폴링 전략

1. **고유한 출력 재정의:** API는 각 요청에 대해 고유한 임시 디렉터리를 생성합니다.
2. **프로세스 시작:** 비차단 스레드에서 핵심 로직을 실행하기 위해 `process_text_in_Background`를 호출하고 해당 고유 폴더 내의 `tts_output_*.txt` 파일에 결과를 씁니다.
3. **동기 대기:** 그런 다음 API 기능은 출력 파일이 생성되거나 시간 초과에 도달할 때까지 고유 폴더를 **차단**하고 폴링합니다.
4. **결과 전달:** API는 파일의 내용을 읽고 필요한 정리(파일 및 임시 디렉터리 삭제)를 수행한 다음 JSON 응답의 `result_text` 필드에 최종 처리된 텍스트를 반환합니다.

이렇게 하면 CLI 클라이언트가 텍스트 처리가 완료된 *후*에만 응답을 수신하여 안정적인 셸 경험을 보장할 수 있습니다.

## 2. 원격 액세스 및 네트워크 포트 매핑

Lub의 터미널과 같은 원격 클라이언트에서의 액세스를 허용하려면 제한된 외부 포트 가용성이라는 일반적인 제약 조건을 해결하기 위해 다음과 같은 네트워크 구성이 필요했습니다.

### 해결 방법: 외부 포트 매핑

서비스는 내부적으로 **포트 8000**에서 실행되고 당사의 네트워크 환경은 외부 액세스를 특정 포트 범위(예: `88__-8831`)로 제한하므로 라우터(Fritz!Box)에 **포트 매핑**을 구현했습니다.

| 엔드포인트 | 프로토콜 | 포트 | 설명 |
| :--- | :--- | :--- | :--- |
| **외부/공개** | TCP | `88__` (예) | 클라이언트(Lub)가 사용해야 하는 포트입니다. |
| **내부/로컬** | TCP | `8000` | FastAPI 서비스가 실제로 수신 대기하는 포트입니다(`--port 8000`). |

라우터는 외부 포트('88__')에서 들어오는 모든 연결을 호스트 시스템의 내부 포트('8000')로 변환하여 코어 서버 구성을 변경하지 않고도 서비스에 전역적으로 액세스할 수 있도록 합니다.

## 3. CLI 클라이언트 사용법

클라이언트는 공용 IP 주소, 외부 포트 및 올바른 API 키로 구성되어야 합니다.

### 최종 명령 구문

__CODE_BLOCK_0__