diff --git a/.env.example b/.env.example
index 036f851..4206050 100644
--- a/.env.example
+++ b/.env.example
@@ -152,3 +152,21 @@ REPORT_MAX_MESSAGES=200
 
 # MinIO path prefix for generated reports (default: reports)
 REPORT_STORAGE_PATH=reports
+
+# -----------------------------------------------------------------------------
+# Development Scripts Port Configuration
+# -----------------------------------------------------------------------------
+# These ports are used by start-dev.sh, start-prod.sh, and check-env.sh scripts.
+# They should match the actual service ports configured above.
+
+# Backend API port for scripts (default: 8000, should match PORT above)
+BACKEND_PORT=8000
+
+# Frontend development server port (default: 3000)
+FRONTEND_PORT=3000
+
+# MinIO S3 API port for Docker container (default: 9000)
+MINIO_API_PORT=9000
+
+# MinIO Web Console port for Docker container (default: 9001)
+MINIO_CONSOLE_PORT=9001
diff --git a/.gitignore b/.gitignore
index dce07a9..89e16c3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,12 +8,19 @@ venv/
 env/
 ENV/
 
+# Python cache
+.cache/
+.ruff_cache/
+.mypy_cache/
+
 # Database
 *.db
 *.db-journal
 
 # Environment
 .env
+.env.local
+.env.docker
 
 # IDE
 .vscode/
@@ -25,6 +32,7 @@ ENV/
 .pytest_cache/
 .coverage
 htmlcov/
+tests/__pycache__/
 
 # Project specific
 task_reporter.db
@@ -34,7 +42,16 @@ server.log
 node_modules/
 frontend/dist/
 frontend/.vite/
+frontend/.cache/
+.eslintcache
 
 # Development scripts
 .pids/
 logs/
+
+# Development documentation (AI/OpenSpec)
+openspec/
+AGENTS.md
+CLAUDE.md
+PROGRESS.md
+.claude/
diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
new file mode 100644
index 0000000..f563edb
--- /dev/null
+++ b/DEPLOYMENT.md
@@ -0,0 +1,395 @@
+# Task Reporter 部署指南 (1Panel)
+
+本文件說明如何透過 1Panel 部署 Task Reporter 系統。
+
+## 系統需求
+
+### 必要服務
+- **MySQL 8.0+** - 資料庫
+- **MinIO** - 物件儲存 (檔案上傳)
+- **Python 3.11+** - 後端運行環境
+- **Node.js 18+** - 前端建置
+
+### 建議配置
+- CPU: 2 核心以上
+- RAM: 4GB 以上
+- 儲存: 20GB 以上 (依據檔案上傳量調整)
+
+---
+
+## 內建腳本
+
+專案提供了一組便利腳本,簡化環境檢查和服務管理:
+
+| 腳本 | 說明 |
+|------|------|
+| `./check-env.sh` | 檢查環境設定 (Python, Node.js, MySQL, MinIO, 環境變數) |
+| `./start-dev.sh` | 啟動開發環境 (MinIO + Backend + Frontend with hot-reload) |
+| `./stop-dev.sh` | 停止開發環境所有服務 |
+| `./start-prod.sh` | 啟動生產環境 (MinIO + Backend with multi-workers) |
+| `./stop-prod.sh` | 停止生產環境所有服務 |
+
+### 快速開始 (使用腳本)
+
+```bash
+# 1. 檢查環境是否就緒
+./check-env.sh
+
+# 2. 設定環境變數
+cp .env.example .env
+nano .env
+
+# 3. 執行資料庫遷移
+source venv/bin/activate
+alembic upgrade head
+
+# 4. 啟動開發環境
+./start-dev.sh
+
+# 或啟動生產環境
+./start-prod.sh
+```
+
+### 腳本功能說明
+
+**check-env.sh**:
+- 檢查 Python 版本 (3.11+)
+- 檢查 Node.js 版本 (18+)
+- 驗證 MySQL 連線
+- 驗證 MinIO 連線
+- 檢查必要環境變數
+- 驗證 FERNET_KEY 格式
+
+**start-dev.sh / start-prod.sh**:
+- 自動啟動 MinIO Docker 容器
+- 啟動後端 API 服務
+- 啟動前端開發伺服器 (dev) 或靜態服務 (prod)
+- PID 檔案儲存於 `.pids/`
+- 日誌輸出至 `logs/`
+
+**stop-dev.sh / stop-prod.sh**:
+- 優雅停止所有服務
+- 清理 PID 檔案
+
+---
+
+## 部署步驟
+
+### 1. 安裝 MySQL
+
+在 1Panel 的「應用商店」中安裝 MySQL:
+
+1. 搜尋並安裝 MySQL
+2. 記錄以下資訊:
+   - 主機: `localhost` 或容器名稱
+   - 埠號: `3306`
+   - root 密碼
+
+3. 建立資料庫:
+```sql
+CREATE DATABASE task_reporter CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+CREATE USER 'taskreporter'@'%' IDENTIFIED BY '你的密碼';
+GRANT ALL PRIVILEGES ON task_reporter.* TO 'taskreporter'@'%';
+FLUSH PRIVILEGES;
+```
+
+### 2. 安裝 MinIO
+
+在 1Panel 的「應用商店」中安裝 MinIO:
+
+1. 搜尋並安裝 MinIO
+2. 設定 Access Key 和 Secret Key (建議使用強密碼)
+3. 記錄 API 端點 (預設 `localhost:9000`)
+4. 系統啟動時會自動建立 bucket
+
+### 3. 部署後端 (Python)
+
+#### 方式一: 使用 1Panel 的網站功能
+
+1. 在「網站」中新增 Python 專案
+2. 上傳後端程式碼到指定目錄
+3. 設定虛擬環境:
+
+```bash
+cd /opt/task-reporter
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+4. 複製並編輯環境變數:
+```bash
+cp .env.example .env
+nano .env
+```
+
+5. 執行資料庫遷移:
+```bash
+source venv/bin/activate
+alembic upgrade head
+```
+
+6. 使用 Supervisor 管理程序:
+```ini
+[program:task-reporter]
+directory=/opt/task-reporter
+command=/opt/task-reporter/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
+user=www-data
+autostart=true
+autorestart=true
+stderr_logfile=/var/log/task-reporter/error.log
+stdout_logfile=/var/log/task-reporter/access.log
+```
+
+#### 方式二: 使用 Docker
+
+1. 建立 Dockerfile:
+```dockerfile
+FROM python:3.11-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y \
+    libmagic1 \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+2. 在 1Panel 容器管理中建立並運行
+
+### 4. 部署前端
+
+1. 建置前端:
+```bash
+cd frontend
+cp .env.example .env
+# 編輯 .env 設定 API URL (如果後端不在同一網域)
+npm install
+npm run build
+```
+
+2. 在 1Panel 中建立靜態網站:
+   - 網站類型: 靜態網站
+   - 根目錄: `frontend/dist`
+
+3. 設定反向代理 (Nginx):
+```nginx
+location /api {
+    proxy_pass http://127.0.0.1:8000;
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    # WebSocket 支援
+    proxy_set_header Upgrade $http_upgrade;
+    proxy_set_header Connection "upgrade";
+    proxy_read_timeout 86400;
+}
+
+location / {
+    root /opt/task-reporter/frontend/dist;
+    try_files $uri $uri/ /index.html;
+}
+```
+
+### 5. 環境變數設定
+
+必要的環境變數 (`.env`):
+
+```bash
+# 資料庫
+DATABASE_URL=mysql+pymysql://taskreporter:密碼@localhost:3306/task_reporter?charset=utf8mb4
+
+# 安全金鑰 (產生方式見下方)
+FERNET_KEY=你的金鑰
+
+# MinIO
+MINIO_ENDPOINT=localhost:9000
+MINIO_ACCESS_KEY=你的AccessKey
+MINIO_SECRET_KEY=你的SecretKey
+MINIO_BUCKET=task-reporter-files
+
+# AD 認證
+AD_API_URL=https://pj-auth-api.vercel.app/api/auth/login
+
+# CORS (前端網址)
+CORS_ORIGINS=https://your-domain.com
+
+# DIFY AI (可選)
+DIFY_BASE_URL=https://dify.theaken.com/v1
+DIFY_API_KEY=你的DIFY金鑰
+
+# 端口配置 (用於開發腳本)
+BACKEND_PORT=8000
+FRONTEND_PORT=3000
+MINIO_API_PORT=9000
+MINIO_CONSOLE_PORT=9001
+```
+
+產生 FERNET_KEY:
+```bash
+python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+```
+
+---
+
+## 常見問題排除
+
+### 問題 1: 資料庫連線失敗
+
+**症狀**: `sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError)`
+
+**解決方案**:
+1. 確認 MySQL 服務正在運行
+2. 檢查 DATABASE_URL 格式是否正確
+3. 確認使用者權限:
+```sql
+SHOW GRANTS FOR 'taskreporter'@'%';
+```
+4. 如果使用 Docker,確認網路設定 (使用容器名稱而非 localhost)
+
+### 問題 2: MinIO 連線失敗
+
+**症狀**: `S3 operation failed; code: NoSuchBucket`
+
+**解決方案**:
+1. 確認 MinIO 服務正在運行
+2. 檢查 MINIO_ENDPOINT 是否正確
+3. 確認 Access Key 和 Secret Key
+4. 系統會自動建立 bucket,確認 logs 無錯誤
+
+### 問題 3: WebSocket 連線失敗
+
+**症狀**: 前端顯示連線中斷,無法即時接收訊息
+
+**解決方案**:
+1. 確認 Nginx 反向代理設定包含 WebSocket 標頭
+2. 增加 `proxy_read_timeout` 值
+3. 確認防火牆未阻擋 WebSocket 連線
+4. 檢查 CORS_ORIGINS 是否包含前端網址
+
+### 問題 4: 檔案上傳失敗
+
+**症狀**: 上傳檔案返回 500 錯誤
+
+**解決方案**:
+1. 確認 MinIO 連線正常
+2. 檢查檔案大小限制 (IMAGE_MAX_SIZE_MB, DOCUMENT_MAX_SIZE_MB)
+3. 確認 Nginx client_max_body_size 設定:
+```nginx
+client_max_body_size 50M;
+```
+4. 安裝 libmagic (檔案類型檢測):
+```bash
+apt-get install libmagic1
+```
+
+### 問題 5: DIFY AI 報告生成失敗
+
+**症狀**: 報告生成卡在 pending 或顯示錯誤
+
+**解決方案**:
+1. 確認 DIFY_API_KEY 已設定
+2. 確認 DIFY_BASE_URL 可以存取
+3. 增加 DIFY_TIMEOUT_SECONDS (AI 生成可能較慢)
+4. 檢查 DIFY 服務額度
+
+### 問題 6: 時區顯示錯誤
+
+**症狀**: 訊息時間顯示不正確
+
+**解決方案**:
+1. 系統使用 UTC 儲存,前端轉換為 GMT+8
+2. 確認伺服器時區設定正確
+3. 確認資料庫時區設定:
+```sql
+SELECT @@global.time_zone, @@session.time_zone;
+```
+
+### 問題 7: Alembic 遷移失敗
+
+**症狀**: `alembic upgrade head` 報錯
+
+**解決方案**:
+1. 確認資料庫連線正確
+2. 如果是新安裝,確認 alembic_version 表存在
+3. 檢查遷移歷史:
+```bash
+alembic history
+alembic current
+```
+4. 強制從頭開始 (僅限新安裝):
+```bash
+alembic stamp head
+```
+
+---
+
+## 監控與維護
+
+### 健康檢查
+
+```bash
+# 後端健康檢查
+curl http://localhost:8000/api/health
+
+# DIFY 服務檢查
+curl http://localhost:8000/api/reports/health
+```
+
+### 日誌位置
+
+- 後端日誌: Supervisor 設定的 stderr_logfile / stdout_logfile
+- Nginx 日誌: `/var/log/nginx/access.log`, `/var/log/nginx/error.log`
+
+### 備份策略
+
+1. **資料庫備份**:
+```bash
+mysqldump -u taskreporter -p task_reporter > backup_$(date +%Y%m%d).sql
+```
+
+2. **MinIO 檔案備份**:
+   - 使用 MinIO Client (mc) 同步到其他儲存
+   - 或設定 MinIO 複製功能
+
+### 更新部署
+
+```bash
+# 1. 拉取新版本
+cd /opt/task-reporter
+git pull
+
+# 2. 更新後端依賴
+source venv/bin/activate
+pip install -r requirements.txt
+
+# 3. 執行資料庫遷移
+alembic upgrade head
+
+# 4. 重啟服務
+supervisorctl restart task-reporter
+
+# 5. 重建前端
+cd frontend
+npm install
+npm run build
+```
+
+---
+
+## 安全建議
+
+1. **使用 HTTPS**: 在 1Panel 中設定 SSL 憑證
+2. **修改預設密碼**: MinIO, MySQL 都要使用強密碼
+3. **限制 CORS**: 只允許必要的來源網址
+4. **定期備份**: 設定自動備份排程
+5. **監控異常**: 設定日誌監控和警報
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..cd93f79
--- /dev/null
+++ b/README.md
@@ -0,0 +1,302 @@
+# Task Reporter
+
+Task Reporter 是一個生產事件即時協作報告系統,專為製造業生產線異常事件的追蹤、協作與報告而設計。
+
+## 功能特色
+
+### 核心功能
+- **事件房間管理** - 建立、管理生產異常事件的專屬聊天室
+- **即時訊息** - WebSocket 即時通訊,支援文字訊息及打字指示器
+- **檔案上傳** - 支援圖片、文件、日誌檔案上傳 (MinIO 儲存)
+- **AI 報告生成** - 透過 DIFY 整合自動生成事件報告 (Word 格式)
+- **LOT 批號追蹤** - 關聯受影響的生產批號
+
+### 權限系統
+- **AD 整合認證** - 透過 Active Directory API 進行身份驗證
+- **角色權限** - 房間擁有者 (Owner)、編輯者 (Editor)、檢視者 (Viewer)
+- **開放房間存取** - 所有登入用戶可自由加入房間
+- **系統管理員** - 特殊權限帳號,可管理所有房間
+
+### 事件分類
+- **類型**: 設備故障、物料短缺、品質問題、其他
+- **嚴重等級**: 低、中、高、緊急
+- **狀態**: 進行中、已解決、已封存
+
+---
+
+## 專案架構
+
+```
+Task_Reporter/
+├── app/                          # 後端 (FastAPI)
+│   ├── core/                     # 核心設定
+│   │   ├── config.py             # 環境變數設定
+│   │   └── database.py           # 資料庫連線
+│   ├── db/                       # 資料庫初始化
+│   ├── modules/                  # 功能模組
+│   │   ├── auth/                 # 認證模組
+│   │   │   ├── models.py         # User, Session 模型
+│   │   │   ├── router.py         # 認證 API
+│   │   │   └── services/         # AD 客戶端
+│   │   ├── chat_room/            # 聊天室模組
+│   │   │   ├── models.py         # Room, RoomMember 模型
+│   │   │   ├── router.py         # 房間管理 API
+│   │   │   └── schemas.py        # Pydantic schemas
+│   │   ├── realtime/             # 即時訊息模組
+│   │   │   ├── models.py         # Message 模型
+│   │   │   ├── router.py         # WebSocket 端點
+│   │   │   ├── websocket_manager.py
+│   │   │   └── services/         # 訊息服務
+│   │   ├── file_storage/         # 檔案儲存模組
+│   │   │   ├── models.py         # FileAttachment 模型
+│   │   │   ├── router.py         # 檔案上傳 API
+│   │   │   └── validators.py     # 檔案驗證
+│   │   └── report_generation/    # 報告生成模組
+│   │       ├── models.py         # Report 模型
+│   │       ├── router.py         # 報告 API
+│   │       └── services/         # DIFY 整合
+│   └── main.py                   # FastAPI 入口
+├── alembic/                      # 資料庫遷移
+│   └── versions/                 # 遷移版本檔
+├── frontend/                     # 前端 (React + Vite)
+│   ├── src/
+│   │   ├── components/           # React 元件
+│   │   ├── hooks/                # 自訂 Hooks
+│   │   ├── pages/                # 頁面元件
+│   │   ├── services/             # API 服務
+│   │   ├── stores/               # Zustand 狀態管理
+│   │   ├── types/                # TypeScript 型別
+│   │   └── utils/                # 工具函數
+│   ├── package.json
+│   └── vite.config.ts
+├── scripts/                      # 工具腳本
+│   └── migrate_orphan_files.py   # 孤立檔案遷移工具
+├── tests/                        # 測試檔案
+├── check-env.sh                  # 環境檢查腳本
+├── start-dev.sh                  # 啟動開發環境
+├── stop-dev.sh                   # 停止開發環境
+├── start-prod.sh                 # 啟動生產環境
+├── stop-prod.sh                  # 停止生產環境
+├── .env.example                  # 後端環境變數範本
+├── .env.docker.example           # Docker 環境變數範本
+├── docker-compose.minio.yml      # MinIO Docker 設定
+├── requirements.txt              # Python 依賴
+├── alembic.ini                   # Alembic 設定
+└── DEPLOYMENT.md                 # 部署指南
+```
+
+---
+
+## 技術棧
+
+### 後端
+- **FastAPI** - 非同步 Web 框架
+- **SQLAlchemy 2.0** - ORM
+- **MySQL** - 關聯式資料庫
+- **Alembic** - 資料庫遷移
+- **MinIO** - S3 相容物件儲存
+- **WebSocket** - 即時通訊
+- **python-docx** - Word 文件生成
+
+### 前端
+- **React 18** - UI 框架
+- **TypeScript** - 型別安全
+- **Vite** - 建置工具
+- **TanStack Query** - 資料同步
+- **Zustand** - 狀態管理
+- **Tailwind CSS** - 樣式框架
+
+### 基礎設施
+- **MinIO** - 物件儲存
+- **DIFY** - AI 服務整合
+
+---
+
+## 快速開始
+
+### 必要條件
+- Python 3.11+
+- Node.js 18+
+- MySQL 8.0+
+- Docker (用於 MinIO)
+
+### 方式一: 使用內建腳本 (推薦)
+
+```bash
+# 1. 檢查環境是否就緒
+./check-env.sh
+
+# 2. 設定環境變數
+cp .env.example .env
+nano .env  # 填入 DATABASE_URL, FERNET_KEY 等
+
+# 3. 建立虛擬環境並安裝依賴
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# 4. 執行資料庫遷移
+alembic upgrade head
+
+# 5. 啟動開發環境 (MinIO + Backend + Frontend)
+./start-dev.sh
+
+# 停止服務
+./stop-dev.sh
+```
+
+### 方式二: 手動啟動
+
+#### 1. 啟動 MinIO
+
+```bash
+docker-compose -f docker-compose.minio.yml up -d
+```
+
+#### 2. 設定後端
+
+```bash
+# 建立虛擬環境
+python3 -m venv venv
+source venv/bin/activate
+
+# 安裝依賴
+pip install -r requirements.txt
+
+# 設定環境變數
+cp .env.example .env
+# 編輯 .env 填入必要設定
+
+# 執行資料庫遷移
+alembic upgrade head
+
+# 啟動後端
+uvicorn app.main:app --reload --port 8000
+```
+
+#### 3. 設定前端
+
+```bash
+cd frontend
+
+# 安裝依賴
+npm install
+
+# 設定環境變數 (可選)
+cp .env.example .env
+
+# 啟動開發伺服器
+npm run dev
+```
+
+### 存取應用
+
+- 前端: http://localhost:3000
+- 後端 API: http://localhost:8000/api
+- API 文件: http://localhost:8000/docs
+- MinIO Console: http://localhost:9001
+
+### 內建腳本說明
+
+| 腳本 | 說明 |
+|------|------|
+| `./check-env.sh` | 檢查環境設定 (Python, Node, MySQL, MinIO, 環境變數) |
+| `./start-dev.sh` | 啟動開發環境 (所有服務 + hot-reload) |
+| `./stop-dev.sh` | 停止開發環境 |
+| `./start-prod.sh` | 啟動生產環境 (multi-worker backend) |
+| `./stop-prod.sh` | 停止生產環境 |
+
+---
+
+## API 端點概覽
+
+### 認證 (`/api/auth`)
+- `POST /login` - 登入
+- `POST /logout` - 登出
+- `GET /me` - 取得目前用戶資訊
+- `POST /refresh` - 更新 token
+
+### 房間管理 (`/api/rooms`)
+- `GET /` - 列出房間
+- `POST /` - 建立房間
+- `GET /{room_id}` - 取得房間詳情
+- `PATCH /{room_id}` - 更新房間
+- `DELETE /{room_id}` - 封存房間
+- `POST /{room_id}/join` - 加入房間
+- `GET /{room_id}/members` - 取得成員列表
+- `POST /{room_id}/lots` - 新增 LOT 批號
+- `DELETE /{room_id}/lots/{lot}` - 移除 LOT 批號
+
+### 即時訊息 (`/api/realtime`)
+- `WebSocket /ws/{room_id}` - 即時訊息連線
+- `GET /rooms/{room_id}/messages` - 取得歷史訊息
+- `GET /rooms/{room_id}/online-users` - 取得線上用戶
+
+### 檔案管理 (`/api/rooms/{room_id}/files`)
+- `POST /` - 上傳檔案
+- `GET /` - 列出檔案
+- `GET /{file_id}/download` - 下載檔案
+
+### 報告生成 (`/api/rooms/{room_id}/reports`)
+- `POST /generate` - 生成報告
+- `GET /` - 列出報告
+- `GET /{report_id}/status` - 報告狀態
+- `GET /{report_id}/download` - 下載報告
+- `GET /{report_id}/markdown` - 取得 Markdown 預覽
+
+---
+
+## 環境變數
+
+詳見 [.env.example](.env.example) 取得完整設定說明。
+
+### 必要設定
+- `DATABASE_URL` - MySQL 連線字串
+- `FERNET_KEY` - 加密金鑰
+- `AD_API_URL` - AD 認證 API
+- `MINIO_*` - MinIO 連線設定
+
+### 可選設定
+- `DIFY_API_KEY` - AI 報告功能
+- `SYSTEM_ADMIN_EMAIL` - 系統管理員
+
+---
+
+## 部署
+
+詳見 [DEPLOYMENT.md](DEPLOYMENT.md) 取得完整的 1Panel 部署指南。
+
+---
+
+## 開發
+
+### 資料庫遷移
+
+```bash
+# 建立新遷移
+alembic revision --autogenerate -m "描述"
+
+# 執行遷移
+alembic upgrade head
+
+# 回滾
+alembic downgrade -1
+```
+
+### 測試
+
+```bash
+pytest tests/
+```
+
+### 程式碼檢查
+
+```bash
+ruff check app/
+```
+
+---
+
+## 授權
+
+Private - 版權所有
diff --git a/check-env.sh b/check-env.sh
index 5b93441..20f684d 100755
--- a/check-env.sh
+++ b/check-env.sh
@@ -17,6 +17,19 @@ NC='\033[0m' # No Color
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$SCRIPT_DIR"
 
+# Load port configuration from .env file
+if [[ -f "$PROJECT_ROOT/.env" ]]; then
+    BACKEND_PORT="${BACKEND_PORT:-$(grep -E '^BACKEND_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '8000')}"
+    FRONTEND_PORT="${FRONTEND_PORT:-$(grep -E '^FRONTEND_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '3000')}"
+    MINIO_API_PORT="${MINIO_API_PORT:-$(grep -E '^MINIO_API_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '9000')}"
+    MINIO_CONSOLE_PORT="${MINIO_CONSOLE_PORT:-$(grep -E '^MINIO_CONSOLE_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '9001')}"
+else
+    BACKEND_PORT="${BACKEND_PORT:-8000}"
+    FRONTEND_PORT="${FRONTEND_PORT:-3000}"
+    MINIO_API_PORT="${MINIO_API_PORT:-9000}"
+    MINIO_CONSOLE_PORT="${MINIO_CONSOLE_PORT:-9001}"
+fi
+
 # Track overall status
 ERRORS=0
 WARNINGS=0
@@ -60,7 +73,7 @@ show_help() {
     echo "  - Docker availability"
     echo "  - Virtual environment (venv/)"
     echo "  - Environment file (.env)"
-    echo "  - Port availability (8000, 3000, 9000, 9001)"
+    echo "  - Port availability (reads from .env: BACKEND_PORT, FRONTEND_PORT, MINIO_API_PORT, MINIO_CONSOLE_PORT)"
 }
 
 # Parse arguments
@@ -235,10 +248,10 @@ check_port() {
     fi
 }
 
-check_port 8000 "Backend API"
-check_port 3000 "Frontend Dev"
-check_port 9000 "MinIO S3"
-check_port 9001 "MinIO Console"
+check_port "$BACKEND_PORT" "Backend API"
+check_port "$FRONTEND_PORT" "Frontend Dev"
+check_port "$MINIO_API_PORT" "MinIO S3"
+check_port "$MINIO_CONSOLE_PORT" "MinIO Console"
 
 # ============================================================================
 # Summary
diff --git a/start-dev.sh b/start-dev.sh
index 55c63b1..f5ad917 100755
--- a/start-dev.sh
+++ b/start-dev.sh
@@ -18,6 +18,21 @@ NC='\033[0m' # No Color
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$SCRIPT_DIR"
 
+# Load environment variables from .env file
+if [[ -f "$PROJECT_ROOT/.env" ]]; then
+    # Export only specific port variables to avoid overriding shell environment
+    export BACKEND_PORT="${BACKEND_PORT:-$(grep -E '^BACKEND_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '8000')}"
+    export FRONTEND_PORT="${FRONTEND_PORT:-$(grep -E '^FRONTEND_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '3000')}"
+    export MINIO_API_PORT="${MINIO_API_PORT:-$(grep -E '^MINIO_API_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '9000')}"
+    export MINIO_CONSOLE_PORT="${MINIO_CONSOLE_PORT:-$(grep -E '^MINIO_CONSOLE_PORT=' "$PROJECT_ROOT/.env" 2>/dev/null | cut -d'=' -f2 || echo '9001')}"
+else
+    # Default values if .env doesn't exist
+    export BACKEND_PORT="${BACKEND_PORT:-8000}"
+    export FRONTEND_PORT="${FRONTEND_PORT:-3000}"
+    export MINIO_API_PORT="${MINIO_API_PORT:-9000}"
+    export MINIO_CONSOLE_PORT="${MINIO_CONSOLE_PORT:-9001}"
+fi
+
 # PID file locations
 PID_DIR="$PROJECT_ROOT/.pids"
 BACKEND_PID_FILE="$PID_DIR/backend.pid"
@@ -62,9 +77,9 @@ show_help() {
     echo "  --no-minio         Don't start MinIO (use external)"
     echo ""
     echo "Services started:"
-    echo "  - MinIO (Object Storage) - http://localhost:9000 (API), http://localhost:9001 (Console)"
-    echo "  - Backend (FastAPI)      - http://localhost:8000"
-    echo "  - Frontend (Vite)        - http://localhost:3000"
+    echo "  - MinIO (Object Storage) - http://localhost:\$MINIO_API_PORT (API), http://localhost:\$MINIO_CONSOLE_PORT (Console)"
+    echo "  - Backend (FastAPI)      - http://localhost:\$BACKEND_PORT"
+    echo "  - Frontend (Vite)        - http://localhost:\$FRONTEND_PORT"
 }
 
 # Cleanup function for graceful shutdown
@@ -151,7 +166,7 @@ if [[ "$NO_MINIO" == "false" ]]; then
         print_info "Waiting for MinIO to be healthy..."
         MINIO_READY=false
         for i in {1..30}; do
-            if curl -s http://localhost:9000/minio/health/live > /dev/null 2>&1; then
+            if curl -s "http://localhost:$MINIO_API_PORT/minio/health/live" > /dev/null 2>&1; then
                 MINIO_READY=true
                 break
             fi
@@ -168,7 +183,7 @@ if [[ "$NO_MINIO" == "false" ]]; then
         fi
     fi
 
-    print_info "MinIO Console: http://localhost:9001 (minioadmin/minioadmin)"
+    print_info "MinIO Console: http://localhost:$MINIO_CONSOLE_PORT (minioadmin/minioadmin)"
 fi
 
 # ============================================================================
@@ -189,7 +204,7 @@ else
     (
         source "$PROJECT_ROOT/venv/bin/activate"
         cd "$PROJECT_ROOT"
-        uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 > "$BACKEND_LOG" 2>&1 &
+        uvicorn app.main:app --reload --host 0.0.0.0 --port "$BACKEND_PORT" > "$BACKEND_LOG" 2>&1 &
         echo $! > "$BACKEND_PID_FILE"
     )
 
@@ -197,7 +212,7 @@ else
     print_info "Waiting for backend to be ready..."
     BACKEND_READY=false
     for i in {1..15}; do
-        if curl -s http://localhost:8000/api/health > /dev/null 2>&1 || curl -s http://localhost:8000/docs > /dev/null 2>&1; then
+        if curl -s "http://localhost:$BACKEND_PORT/api/health" > /dev/null 2>&1 || curl -s "http://localhost:$BACKEND_PORT/docs" > /dev/null 2>&1; then
             BACKEND_READY=true
             break
         fi
@@ -213,8 +228,8 @@ else
     fi
 fi
 
-print_info "Backend API: http://localhost:8000"
-print_info "API Docs: http://localhost:8000/docs"
+print_info "Backend API: http://localhost:$BACKEND_PORT"
+print_info "API Docs: http://localhost:$BACKEND_PORT/docs"
 
 # ============================================================================
 # Start Frontend
@@ -248,7 +263,7 @@ if [[ "$NO_FRONTEND" == "false" ]]; then
         fi
     fi
 
-    print_info "Frontend: http://localhost:3000"
+    print_info "Frontend: http://localhost:$FRONTEND_PORT"
 fi
 
 # ============================================================================
@@ -260,10 +275,10 @@ echo -e "${GREEN}============================================${NC}"
 echo -e "${GREEN}  All services are running!${NC}"
 echo -e "${GREEN}============================================${NC}"
 echo ""
-echo -e "  ${CYAN}Frontend:${NC}      http://localhost:3000"
-echo -e "  ${CYAN}Backend API:${NC}   http://localhost:8000"
-echo -e "  ${CYAN}API Docs:${NC}      http://localhost:8000/docs"
-echo -e "  ${CYAN}MinIO Console:${NC} http://localhost:9001"
+echo -e "  ${CYAN}Frontend:${NC}      http://localhost:$FRONTEND_PORT"
+echo -e "  ${CYAN}Backend API:${NC}   http://localhost:$BACKEND_PORT"
+echo -e "  ${CYAN}API Docs:${NC}      http://localhost:$BACKEND_PORT/docs"
+echo -e "  ${CYAN}MinIO Console:${NC} http://localhost:$MINIO_CONSOLE_PORT"
 echo ""
 echo -e "  ${YELLOW}Logs:${NC}"
 echo -e "    Backend:  $BACKEND_LOG"