Merge pull request '[MR]Added readme.md' (#3) from develop into main

Reviewed-on: #3

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