SalesPipeline/README.md

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 專案

   git clone <your-repo>
   cd SampleOrderAssistant
   

2. 設定後端

   cd backend
   python -m venv venv
   
   # Windows
   venv\Scripts\activate
   
   # Linux/Mac
   source venv/bin/activate
   
   pip install -r requirements.txt
   

3. 設定環境變數

   cp .env.example .env
   # 編輯 .env 檔案設定資料庫連線
   

4. 設定前端

   cd frontend
   npm install
   

開發模式

1. 啟動後端 (Port 8000)

   cd backend
   python run.py
   

2. 啟動前端 (Port 3000)

   cd frontend
   npm run dev
   

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

生產環境部署

1. 建置前端

   cd frontend
   npm run build
   

2. 啟動服務

   cd backend
   python run.py
   

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

詳細部署說明請參考 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