203 lines
4.7 KiB
Markdown
203 lines
4.7 KiB
Markdown
# 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
|