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)

---

아키텍처

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 서버와 사용할 모델

실행

cd mail_summary
docker compose up -d --build

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

자주 쓰는 명령

# 전체 재빌드
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를 수행합니다.

---

디렉터리 구조

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은 저장소에 올리지 않는 것을 권장합니다. )