From 77af89aed78029588002572595f322e2983a1cfe Mon Sep 17 00:00:00 2001
From: nad4-su <nad4.su@gmail.com>
Date: Sat, 11 Apr 2026 23:22:13 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20Docker=20=EC=8B=A4=ED=96=89=20=EA=B0=80?=
 =?UTF-8?q?=EC=9D=B4=EB=93=9C=20=ED=8F=AC=ED=95=A8=20=ED=95=9C=EA=B8=80=20?=
 =?UTF-8?q?README=20=EC=9E=91=EC=84=B1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 139 +++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 118 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index e215bc4..1e160e0 100644
--- a/README.md
+++ b/README.md
@@ -1,36 +1,133 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Meeting Minutes - 회의록 자동 작성 서비스
 
-## Getting Started
+음성 녹음을 텍스트로 변환하고, 구조화된 회의록을 자동 생성하는 웹 서비스입니다.
 
-First, run the development server:
+## 주요 기능
+
+- **실시간 녹음** — 브라우저에서 바로 음성 인식 (Web Speech API, Chrome 권장)
+- **파일 업로드** — MP3, WAV, WebM, M4A, OGG, FLAC 지원 (최대 500MB)
+- **두 가지 변환 모드** — 단순 STT→마크다운 변환 / Gemini AI 요약 비교
+- **내보내기** — 마크다운(.md), HTML(.html) 다운로드 및 클립보드 복사
+- **회의록 저장** — PostgreSQL 데이터베이스 영속 저장
+
+## 기술 스택
+
+| 구분 | 기술 |
+|------|------|
+| 프레임워크 | Next.js 16 + TypeScript |
+| STT | Web Speech API (무료) |
+| AI 요약 | Gemini API (무료 티어) |
+| DB | PostgreSQL 16 + Prisma ORM |
+| 테스트 | Vitest (31개 테스트, 96% 커버리지) |
+| 배포 | Docker Compose |
+
+## Docker로 실행하기
+
+### 사전 요구사항
+
+- [Docker](https://docs.docker.com/get-docker/) 및 [Docker Compose](https://docs.docker.com/compose/install/) 설치
+
+### 1. 저장소 클론
 
 ```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+git clone git@github.com:nad4-su/meeting-minutes.git
+cd meeting-minutes
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+### 2. 환경 변수 설정
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+```bash
+cp .env.example .env
+```
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+`.env` 파일을 열어 필요한 값을 수정합니다:
 
-## Learn More
+```env
+# PostgreSQL (기본값 사용 가능)
+DATABASE_URL="postgresql://meetinguser:meetingpass@db:5432/meetingminutes"
+POSTGRES_USER=meetinguser
+POSTGRES_PASSWORD=meetingpass
+POSTGRES_DB=meetingminutes
 
-To learn more about Next.js, take a look at the following resources:
+# Gemini API (선택사항 - AI 요약 기능에 필요)
+# https://aistudio.google.com/apikey 에서 무료 발급
+GEMINI_API_KEY=여기에_API_키_입력
+```
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+> Gemini API 키가 없어도 **단순 변환** 모드는 정상 동작합니다.
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+### 3. Docker Compose 실행
 
-## Deploy on Vercel
+```bash
+docker compose up -d
+```
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+처음 실행 시 이미지 빌드에 시간이 걸릴 수 있습니다.
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+### 4. DB 마이그레이션
+
+```bash
+docker compose exec app npx prisma migrate deploy
+```
+
+### 5. 접속
+
+브라우저에서 [http://localhost:3000](http://localhost:3000)에 접속합니다.
+
+### 서비스 관리
+
+```bash
+# 로그 확인
+docker compose logs -f app
+
+# 서비스 중지
+docker compose down
+
+# 서비스 중지 + DB 데이터 삭제
+docker compose down -v
+
+# 이미지 재빌드 (코드 변경 후)
+docker compose up -d --build
+```
+
+## 로컬 개발 (Docker 없이)
+
+```bash
+npm install
+npm run dev
+```
+
+[http://localhost:3000](http://localhost:3000)에서 확인합니다.
+
+### 테스트
+
+```bash
+npm test                # 전체 테스트
+npm run test:watch      # 워치 모드
+npm run test:coverage   # 커버리지 리포트
+```
+
+## 프로젝트 구조
+
+```
+src/
+├── app/
+│   ├── api/
+│   │   ├── upload/route.ts         # 파일 업로드 API
+│   │   └── summarize/route.ts      # 회의록 생성 API
+│   ├── page.tsx                    # 메인 UI
+│   └── layout.tsx
+├── lib/
+│   ├── audio-validation.ts         # 오디오 파일 검증
+│   ├── upload-handler.ts           # 업로드 처리
+│   ├── transcript-formatter.ts     # STT 결과 포매팅
+│   ├── minutes-generator.ts        # 회의록 생성 (단순/Gemini)
+│   └── export-minutes.ts           # MD/HTML 내보내기
+├── hooks/
+│   └── useSpeechRecognition.ts     # 실시간 음성 인식 훅
+├── components/
+│   ├── upload/AudioUploader.tsx
+│   ├── recorder/LiveRecorder.tsx
+│   └── minutes/MinutesViewer.tsx
+└── __tests__/                      # 31개 테스트
+```