From 82284f7aab09c4e0408e70e9d97bb7c4c9e2016c Mon Sep 17 00:00:00 2001 From: KYUNGMO TAK Date: Mon, 20 Jul 2026 11:28:26 +0900 Subject: [PATCH] Added readme.md --- README.md | 204 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 204 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..4e43097 --- /dev/null +++ b/README.md @@ -0,0 +1,204 @@ +# 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은 저장소에 올리지 않는 것을 권장합니다. +)