# SalesPipeline - 銷售管線管理系統

一個完整的銷售管線追蹤系統，用於管理 DIT (Design-In Tracking) 案件、樣品紀錄、訂單明細，並提供智慧模糊比對與分析儀表板。

## 系統架構

```
Frontend (React + TypeScript + i18n)
         │
         │ REST API (Single Port)
         ▼
Backend (FastAPI + SQLAlchemy)
         │
         ▼
Database (MySQL)
```

## 功能特色

- **使用者驗證**：JWT 登入/註冊、角色權限管理
- **多語言支援**：繁體中文、英文 (i18next)
- **資料匯入**：自動偵測 Excel 表頭位置，支援中文欄位對應
- **智慧模糊比對**：使用 rapidfuzz 計算客戶名稱相似度
  - ≥95%：自動匹配
  - 80-95%：需人工審核
  - <80%：不匹配
- **分析儀表板**：KPI 統計、轉換漏斗圖、歸因明細表
- **報表匯出**：支援 Excel 和 PDF 格式
- **單一 Port 部署**：前後端整合於同一服務

## 快速開始

### 前置需求

- Node.js 18+
- Python 3.10+
- MySQL 5.7+ / 8.0+

### 安裝步驟

1. **Clone 專案**
   ```bash
   git clone <your-repo>
   cd SampleOrderAssistant
   ```

2. **設定後端**
   ```bash
   cd backend
   python -m venv venv

   # Windows
   venv\Scripts\activate

   # Linux/Mac
   source venv/bin/activate

   pip install -r requirements.txt
   ```

3. **設定環境變數**
   ```bash
   cp .env.example .env
   # 編輯 .env 檔案設定資料庫連線
   ```

4. **設定前端**
   ```bash
   cd frontend
   npm install
   ```

### 開發模式

1. **啟動後端** (Port 8000)
   ```bash
   cd backend
   python run.py
   ```

2. **啟動前端** (Port 3000)
   ```bash
   cd frontend
   npm run dev
   ```

3. 打開瀏覽器前往 http://localhost:3000

### 生產環境部署

1. **建置前端**
   ```bash
   cd frontend
   npm run build
   ```

2. **啟動服務**
   ```bash
   cd backend
   python run.py
   ```

3. 打開瀏覽器前往 http://localhost:8000

詳細部署說明請參考 [deploy/1panel-setup.md](deploy/1panel-setup.md)

## API 文件

後端啟動後 (DEBUG=True)，可前往以下網址查看 API 文件：
- Swagger UI: http://localhost:8000/api/docs
- ReDoc: http://localhost:8000/api/redoc

## 專案結構

```
SampleOrderAssistant/
├── frontend/                 # React 前端
│   ├── src/
│   │   ├── components/      # UI 元件
│   │   ├── services/        # API 服務
│   │   ├── hooks/           # Custom Hooks
│   │   ├── i18n/            # 多語言設定
│   │   │   └── locales/     # 語言檔案 (zh-TW, en)
│   │   └── types/           # TypeScript 類型
│   └── package.json
│
├── backend/                  # FastAPI 後端
│   ├── app/
│   │   ├── models/          # 資料模型
│   │   ├── routers/         # API 路由
│   │   ├── services/        # 業務邏輯
│   │   └── utils/           # 工具函數
│   ├── static/              # 前端建置輸出
│   ├── .env                 # 環境變數 (不進版控)
│   ├── .env.example         # 環境變數範本
│   └── requirements.txt
│
├── data/                     # 資料目錄
│   └── uploads/             # 上傳檔案
│
├── deploy/                   # 部署設定
│   ├── 1panel-setup.md      # 1Panel 部署指南
│   ├── salespipeline.service # Systemd 服務檔
│   └── deploy.sh            # 自動部署腳本
│
└── README.md
```

## 資料庫表格

| 表格名稱 | 說明 |
|---------|------|
| PJ_SOA_Users | 使用者帳戶 |
| PJ_SOA_DIT_Records | DIT 案件資料 |
| PJ_SOA_Sample_Records | 樣品記錄 |
| PJ_SOA_Order_Records | 訂單明細 |
| PJ_SOA_Match_Results | 配對結果 |
| PJ_SOA_Review_Logs | 審核日誌 |

## 技術棧

### 前端
- React 18 + TypeScript
- Vite
- TailwindCSS
- Recharts
- React Query
- React Router DOM
- react-i18next
- Axios

### 後端
- FastAPI
- SQLAlchemy 2.0
- MySQL (PyMySQL)
- rapidfuzz
- openpyxl + pandas
- reportlab
- python-jose (JWT)

## 環境變數

| 變數名稱 | 說明 | 預設值 |
|---------|------|--------|
| DB_HOST | 資料庫主機 | localhost |
| DB_PORT | 資料庫端口 | 3306 |
| DB_USER | 資料庫使用者 | root |
| DB_PASSWORD | 資料庫密碼 | - |
| DB_DATABASE | 資料庫名稱 | sales_pipeline |
| SECRET_KEY | JWT 密鑰 | - |
| ALGORITHM | JWT 演算法 | HS256 |
| ACCESS_TOKEN_EXPIRE_MINUTES | Token 過期時間(分鐘) | 1440 |
| APP_HOST | 應用監聽地址 | 0.0.0.0 |
| APP_PORT | 應用監聽端口 | 8000 |
| WORKERS | 工作進程數 | 1 |
| DEBUG | 開發模式 | False |
| TABLE_PREFIX | 資料表前綴 | PJ_SOA_ |
| CORS_ORIGINS | 允許的跨域來源 (逗號分隔) | - |

## License

MIT