# Design: Unify Environment Scripts

## Context

Tool_OCR 是一個 OCR 處理系統，包含 FastAPI 後端和 React 前端。目前的環境設置和啟動流程分散在多個腳本中：

- `setup_dev_env.sh` (341 lines) - 完整的開發環境設置
- `start_backend.sh` (60 lines) - 後端服務啟動
- `start_frontend.sh` (41 lines) - 前端服務啟動
- `download_fonts.sh` - 字體下載 (可選)

**Current Pain Points:**
1. 需要開兩個終端分別啟動前後端
2. 環境變數配置分散在多個 `.env` 文件中
3. 缺少服務狀態檢查和優雅停止機制
4. GPU 配置需要手動驗證

## Goals / Non-Goals

**Goals:**
- 簡化開發環境設置流程
- 統一前後端啟動為單一命令
- 改善錯誤訊息和故障排除體驗
- 確保跨平台兼容性 (Ubuntu, WSL2)

**Non-Goals:**
- 容器化 (Docker) - 保留為未來提案
- 生產環境部署腳本
- 自動化測試環境設置

## Decisions

### 1. Unified Startup Script Design

**Decision:** 使用單一 `start.sh` 腳本，支援多種模式

```bash
# Usage examples:
./start.sh              # Start both backend and frontend
./start.sh backend      # Start only backend
./start.sh frontend     # Start only frontend
./start.sh --stop       # Stop all services
./start.sh --status     # Show service status
```

**Rationale:** 保持簡單，使用 bash 內建功能管理子進程，不引入額外依賴如 PM2 或 supervisord。

### 2. Process Management

**Decision:** 使用 PID 文件追蹤進程，支援優雅停止

- PID files stored in `.pid/` directory (gitignored)
- SIGTERM for graceful shutdown
- Fallback to SIGKILL after timeout

### 3. Environment Variable Strategy

**Decision:** 保持分離的 `.env` 文件，但改善文檔

- Root `.env.local` - 共用配置 (database, API keys)
- Frontend `.env.local` - 前端特定配置 (VITE_* variables)
- `.env.example` files updated with all required variables

**Rationale:** 前端 Vite 需要 `VITE_` 前綴的變數，混合會造成困擾。

### 4. Package Dependencies

**Current State:**
- Python: 77 packages in requirements.txt
- Node.js: 17 dependencies + 15 devDependencies

**Key Dependencies to Audit:**
- PaddlePaddle GPU vs CPU selection
- Unused development tools
- Duplicate functionality packages

## Risks / Trade-offs

| Risk | Mitigation |
|------|------------|
| Breaking existing workflows | Keep old scripts as aliases |
| Complex process management | Start simple, add features incrementally |
| WSL2 compatibility issues | Test on clean WSL2 Ubuntu 22.04 |

## Migration Plan

1. Create new `start.sh` alongside existing scripts
2. Update documentation to recommend new script
3. After validation, deprecate old scripts (keep for one release)
4. Remove old scripts in future version

## Open Questions

1. Should we add systemd service files for production?
2. Should we include database migration in startup?
3. Should we add health check retries before opening browser?