# 삐꾸 - 시놀로지 연동 텔레그램 비서봇

시놀로지 NAS의 Calendar(CalDAV) 및 Contacts(CardDAV)와 연동하여 일정 관리, 연락처 검색, AI 질의응답 등을 수행하는 텔레그램 봇입니다.

## ✨ 주요 기능

*   **🗓️ 일정 관리:**
    *   오늘/주간/월간 일정 조회 (`/today`, `/week`, `/month`)
    *   특정 날짜 일정 조회 (`/date`)
    *   키워드 기반 일정 검색 (`/search_events`)
    *   새 일정 추가 (시작/종료 시간 설정 가능) (`/addevent`)
    *   일정 삭제 (`/deleteevent`, 관리자 전용)
*   **🔔 자동 알림:**
    *   매일 아침 지정된 시간에 반복(매월/매년) 일정 미리 알림
*   **👤 연락처 관리:**
    *   이름으로 연락처 상세 정보 검색 (`/findcontact`)
    *   키워드로 연락처 검색 (`/searchcontact`)
    *   새 연락처 추가 (`/addcontact`)
    *   연락처 삭제 (`/deletecontact`, 관리자 전용)
*   **🤖 AI 비서:**
    *   Google Gemini 모델을 이용한 자유로운 질의응답 (`/ask`)
*   **🔐 사용자 관리:**
    *   비밀번호 또는 허용 목록 기반 사용자 인증
    *   관리자 전용 기능 (사용자 차단/해제, 목록 조회 등)
*   **🔔 관리자 알림:**
    *   새 사용자 접속 시 알림
    *   비밀번호 인증 성공 시 알림
    *   비밀번호 오류 횟수 초과 및 차단 시 알림
    *   봇 그룹 퇴장 시 알림

## 🚀 시작하기

### 사전 요구 사항

*   Python 3.10 이상
*   Docker 및 Docker Compose
*   Synology NAS (DSM 7.0 이상 권장)
    *   Calendar 패키지 설치 및 설정 완료 (CalDAV 활성화)
    *   Contacts 패키지 설치 및 설정 완료 (CardDAV 활성화)
*   텔레그램 봇 토큰 (BotFather 통해 생성)
*   Google AI API Key (Google AI Studio 등에서 발급, `/ask` 기능 사용 시)
*   CalDAV/CardDAV 접속 URL 및 계정 정보

### 설치 및 실행 (Docker 사용)

1.  **저장소 복제:**
    ```bash
    git clone https://github.com/[YOUR_GITHUB_USERNAME]/[YOUR_REPOSITORY_NAME].git
    cd [YOUR_REPOSITORY_NAME]
    ```
2.  **`.env` 파일 생성 및 설정:**
    제공된 `.env.example` 파일을 `.env` 파일로 복사한 후, 본인의 환경에 맞게 값을 수정합니다.
    ```bash
    cp .env.example .env
    nano .env # 또는 원하는 편집기 사용
    ```
    *(자세한 환경 변수 설명은 아래 참고)*
3.  **(중요!) 데이터베이스 폴더 생성 및 권한 확인:**
    `docker-compose.yml`에 정의된 볼륨 경로에 맞게 호스트 시스템에 폴더를 생성하고, Docker가 해당 폴더에 쓸 수 있도록 권한을 확인/설정해야 할 수 있습니다. (예: `mkdir -p /volume1/docker/bot_bhrm/data` 후 권한 설정)
4.  **Docker 이미지 빌드:**
    ```bash
    docker compose build
    ```
5.  **Docker 컨테이너 실행:**
    ```bash
    docker compose up -d
    ```
6.  **봇 작동 확인:** 텔레그램에서 생성한 봇에게 `/start` 메시지를 보내 정상적으로 응답하는지 확인합니다.

## ⚙️ 환경 설정 (`.env` 파일)

`.env` 파일에 다음 환경 변수들을 설정해야 합니다.

```dotenv
# --- 필수 설정 ---
TELEGRAM_BOT_TOKEN=YOUR_TELEGRAM_BOT_TOKEN_HERE
BOT_PASSWORD=SET_A_SECURE_PASSWORD_FOR_BOT_AUTH

# CalDAV (Synology Calendar) - 본인 환경의 URL 및 계정 정보로 수정하세요!
CALDAV_URL=https://[YOUR_NAS_DDNS_OR_IP]:[PORT]/caldav
CALDAV_USERNAME=YOUR_CALDAV_USERNAME
CALDAV_PASSWORD=YOUR_CALDAV_PASSWORD

# CardDAV (Synology Contacts) - 본인 환경의 URL 및 계정 정보로 수정하세요!
# 주소록 이름(addressbook) 부분은 실제 설정에 따라 다를 수 있습니다.
CARDDAV_URL=https://[YOUR_NAS_DDNS_OR_IP]:[PORT]/carddav/your API
CARDDAV_USERNAME=YOUR_CARDDAV_USERNAME
CARDDAV_PASSWORD=YOUR_CARDDAV_PASSWORD

# 관리자 Telegram Chat ID (숫자 ID) - 알림 수신 및 관리자 명령어 사용
TARGET_CHAT_ID=YOUR_ADMIN_NUMERIC_CHAT_ID

# --- 선택 설정 ---
# Google AI API Key (AI 기능(/ask) 사용 시 필요)
GOOGLE_API_KEY=YOUR_GOOGLE_AI_API_KEY_HERE

# 시간대 설정 (기본값: Asia/Seoul)
TZ=Asia/Seoul

# 신뢰된 사용자 ID 목록 (쉼표로 구분된 숫자 ID, 자동 인증됨)
TRUSTED_USER_IDS=ID1,ID2

#📝 사용법
#봇과의 채팅창에서 / 를 입력하면 사용 가능한 명령어 목록이 나타납니다. /start 또는 /help 명령어를 통해서도 기능 목록을 확인할 수 있습니다. 대화형 명령어 진행 중에는 /cancel 로 언제든지 취소할 수 있습니다.

#📜 라이선스
#이 프로젝트는 MIT 라이선스 하에 배포됩니다.

#🙏 기여하기
#버그를 발견하거나 개선 아이디어가 있다면 GitHub Issues를 통해 알려주세요. 코드 기여(Pull Request)도 언제나 환영합니다!

#📞 연락처
#[fauna035@gmail.com]