# Mail Summary

로컬 LLM으로 한 주 치 메일 백업(`.eml` zip)을 분석해 **주간 업무보고(금주 / 차주)** 를 자동 정리하는 온프레미스 도구입니다.

메일은 외부 AI로 전송하지 않고, 지정한 Ollama 엔드포인트에서만 요약합니다.

**버전:** 1.0.0  
**프로덕션 URL:** https://ms.takits.me  
**로컬 URL:** http://localhost:4888

---

## 주요 기능

- 받은함 / 보낸함 `.zip` 업로드 (대용량 zip 지원, nginx 최대 약 20GB)
- 기간·메일함 범위 지정 후 분석 작업 생성
- 진행 상태 폴링 (준비 → 스캔·필터 → LLM 요약 → 완료)
- 고객(은행/거래처) 단위 **금주 / 차주** 업무보고 UI
- 보고서 원클릭 복사
- DB / LLM 상태 표시 (`LLM(on-prem · 30B)`, `v1.0.0`)

---

## 아키텍처

```text
Browser
  └─ frontend (nginx :4888)
       ├─ static React build
       └─ /api/*  →  backend (FastAPI)
                        ├─ Postgres 15.6
                        └─ Ollama (LLM_BASE_URL)
```

| 구성 | 기술 |
|------|------|
| Frontend | React + Vite, nginx |
| Backend | FastAPI, Python 3.12 |
| DB | PostgreSQL 15.6 |
| LLM | Ollama (예: `qwen3:30b-a3b-instruct-2507-q4_K_M`) |
| 배포 | Docker Compose |

### 분석 파이프라인

1. zip에서 `.eml` 추출
2. 기간·노이즈 필터 (프로모션/불필요 메일 등)
3. 스레드 단위 LLM 요약
4. 주간 보고 JSON 생성 (`this_week` / `next_week` — 고객별 항목)
5. 본문 정리(purge) 후 보고 결과만 유지

---

## 빠른 시작

### 요구사항

- Docker / Docker Compose
- 접근 가능한 Ollama 서버와 사용할 모델

### 실행

```bash
cd mail_summary
docker compose up -d --build
```

- 웹 UI: http://localhost:4888  
- Postgres (호스트): `localhost:5437`

### 자주 쓰는 명령

```bash
# 전체 재빌드
docker compose up -d --build

# 프론트만 재빌드
docker compose up -d --build frontend

# 백엔드만 재시작 (env 변경 후)
docker compose up -d --force-recreate backend

# 로그
docker compose logs -f backend
docker compose logs -f frontend
```

---

## 환경 변수

### 루트 `.env` (Compose)

| 변수 | 설명 | 예시 |
|------|------|------|
| `APP_NAME` | 컨테이너 이름 prefix | `mail_summary` |
| `FRONTEND_PORT` | 웹 UI 포트 | `4888` |
| `POSTGRES_PORT` | DB 호스트 포트 | `5437` |
| `POSTGRES_USER` / `PASSWORD` / `DB` | DB 접속 정보 | — |
| `UPLOAD_HOST` | 업로드 저장 호스트 경로 | `./backend/uploads` |

Synology 등에서는 `UPLOAD_HOST`를 실제 호스트 경로로 지정합니다.

### `backend/.env`

| 변수 | 설명 |
|------|------|
| `CORS_ORIGINS` | 허용 Origin (쉼표 구분) |
| `LLM_BASE_URL` | Ollama base URL |
| `LLM_MODEL` | 사용할 모델명 |
| `LLM_TIMEOUT_SECONDS` | LLM 타임아웃 |
| `LLM_MAX_MAILS` | 분석에 넣을 최대 메일 수 |
| `LLM_BODY_CHARS` | 메일 본문 전달 최대 글자 수 |
| `UPLOAD_DIR` | 컨테이너 내 업로드 경로 (`/app/uploads`) |

`DATABASE_URL`은 Compose가 Postgres 서비스로 주입합니다.

### `frontend/.env` (빌드 시점)

| 변수 | 설명 |
|------|------|
| `VITE_APP_NAME` | UI 앱 이름 |
| `VITE_APP_VERSION` | UI 버전 표시 |
| `VITE_SITE_URL` | OG 메타 URL (예: `https://ms.takits.me`) |

프론트 env를 바꾼 뒤에는 **frontend 재빌드**가 필요합니다.

---

## 사용 방법

1. **01 업로드** — 받은함 / 보낸함 zip 업로드 (둘 중 하나만도 가능)
2. **02 조건** — 시작일·종료일·분석 범위 선택 후 **분석 시작**
3. **03 결과** — 진행률 확인 → 금주/차주 보고 확인 → 복사 / 조건으로 돌아가기 / 새 분석

---

## API 개요

| Method | Path | 설명 |
|--------|------|------|
| `GET` | `/api/health` | DB·LLM 상태 |
| `POST` | `/api/uploads` | mailbox zip 업로드 |
| `DELETE` | `/api/uploads/{upload_id}` | 스테이징 삭제 |
| `POST` | `/api/jobs` | 분석 작업 생성 |
| `GET` | `/api/jobs/{id}` | 작업 상태 |
| `GET` | `/api/jobs/{id}/report` | 주간 보고 |
| `GET` | `/api/jobs` | 작업 목록 |

프론트 nginx가 `/api/*`를 backend로 프록시합니다.

---

## DB 테이블

- `analysis_jobs` — 작업 상태·기간·진행률
- `mails` — 필터된 메일·스레드 요약 (본문은 분석 후 purge 가능)
- `weekly_reports` — 최종 주간 보고 JSON / markdown

스키마: `db/init/01_schema.sql` (컨테이너 최초 기동 시 적용). 백엔드도 기동 시 idempotent `CREATE TABLE IF NOT EXISTS`를 수행합니다.

---

## 디렉터리 구조

```text
mail_summary/
├── compose.yaml
├── .env                 # Compose / 포트 / 업로드 경로
├── db/init/             # Postgres init SQL
├── backend/
│   ├── .env             # LLM, CORS 등
│   ├── app.py           # FastAPI
│   ├── pipeline.py      # 분석·보고 파이프라인
│   ├── mail_parser.py
│   ├── llm_client.py
│   └── uploads/         # zip 스테이징·작업 파일
└── frontend/
    ├── .env             # VITE_*
    ├── nginx.conf
    └── src/             # React UI
```

---

## 도메인 배포 메모

앱 설정:

- `frontend/.env` → `VITE_SITE_URL=https://ms.takits.me`
- `backend/.env` → `CORS_ORIGINS`에 `https://ms.takits.me` 포함

인프라:

- DNS: `ms.takits.me` → 서버
- 리버스 프록시에서 HTTPS 종료 후 `FRONTEND_PORT`(기본 4888)로 프록시

---

## 보안·운영 참고

- 메일 원문은 분석용으로만 쓰고, 보고 생성 후 본문은 purge하는 흐름입니다.
- zip·업로드 데이터는 `UPLOAD_HOST` 경로에 남습니다. 운영 환경에서는 디스크·권한을 관리하세요.
- `.env`의 DB 비밀번호·LLM URL은 저장소에 올리지 않는 것을 권장합니다.
)