first commit

README.md

@@ -0,0 +1,202 @@
+# 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