DIT_C/DIT_C/docs/SDD.md

DIT 智能分析系統 - 系統設計文件 (SDD)

版本: v1.2 日期: 2025-12-12 狀態: 已實作並測試通過

---

1. 系統概述

1.1 專案名稱

DIT (Design-In Tracking) Intelligent Analytics Module

1.2 目標

解析 DIT CSV 報表，透過規則引擎自動產出「行動建議卡片 (Action Cards)」

1.3 技術堆疊

• Backend: Python 3.9+, Flask 3.0+
• Database: MySQL (SQLAlchemy ORM)
• Frontend: Jinja2 Templates, Vanilla JS
• LLM Integration: Ollama API (deepseek-reasoner)
• Version Control: Git + Gitea
• Server Port: 9000 (預設)

1.4 支援檔案格式

• CSV (.csv) - 預設從 B17 儲存格開始讀取
• Excel (.xlsx) - 使用 openpyxl 引擎

---

2. 系統架構

┌─────────────────────────────────────────────────────────┐
│                      Frontend                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │  Dashboard  │  │   Upload    │  │   History   │     │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
└─────────┼────────────────┼────────────────┼─────────────┘
          │                │                │
          ▼                ▼                ▼
┌─────────────────────────────────────────────────────────┐
│                    Flask App (app.py)                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │  routes/    │  │  services/  │  │   models/   │     │
│  │  - api.py   │  │  - dit_*.py │  │  - dit_*.py │     │
│  │  - main.py  │  │  - llm_*.py │  │             │     │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
└─────────┼────────────────┼────────────────┼─────────────┘
          │                │                │
          ▼                ▼                ▼
┌─────────────────────────────────────────────────────────┐
│                   External Services                      │
│  ┌─────────────┐  ┌─────────────┐                       │
│  │   MySQL     │  │ Ollama API  │                       │
│  │  (db_A102)  │  │(deepseek-   │                       │
│  │             │  │ reasoner)   │                       │
│  └─────────────┘  └─────────────┘                       │
└─────────────────────────────────────────────────────────┘

---

3. 核心模組

3.1 DITAnalyzer (services/dit_analyzer.py)

主要分析引擎，負責：

1. 資料載入 (CSV/XLSX)
2. 資料預處理
3. Feature 6.2: 高價值資源分配分析
4. Feature 6.3: 呆滯案件警示
5. 報告生成

class DITAnalyzer:
    def __init__(self, file_path, dataframe, skip_rows=16, start_col=1)
    def load_data(file_path, skip_rows, start_col)
    def _load_excel(file_path, skip_rows, start_col)  # 新增
    def _load_csv(file_path, skip_rows, start_col)    # 新增
    def _preprocess(self)
    def analyze_resource_allocation(top_percent, low_win_rate)
    def analyze_stagnant_deals(threshold_days)
    def generate_report()

資料載入參數:

• skip_rows: 跳過前幾列 (預設 16，即從第 17 列開始)
• start_col: 起始欄位索引 (預設 1，即 B 欄)

3.2 LLMService (services/llm_service.py)

Ollama API 封裝：

• 模型列表查詢
• 一般聊天請求
• 串流模式支援
• SSL 憑證驗證已停用 (內部 API)

預設模型: deepseek-reasoner 備用模型: deepseek-chat

3.3 資料模型 (models/dit_models.py)

Table	說明
DIT_C_upload_history	上傳歷史記錄
DIT_C_analysis_result	分析結果
DIT_C_action_card	行動建議卡片
DIT_C_system_log	系統日誌
DIT_C_llm_config	LLM 設定

---

4. 資料流程

4.1 CSV 上傳分析流程

User Upload CSV/XLSX
      │
      ▼
┌─────────────────┐
│ File Validation │ (check .csv/.xlsx extension)
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Save to uploads/│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  DITAnalyzer    │
│  - preprocess   │
│  - analyze      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Save to DB      │
│ - upload_history│
│ - analysis_result│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Delete temp file│
└────────┬────────┘
         │
         ▼
   Return JSON

---

5. API 端點

Method	Path	說明
GET	/health	健康檢查
GET	/	儀表板
GET	/upload	上傳頁面
GET	/history	歷史記錄
POST	/api/analyze	完整分析
POST	/api/analyze/resource-allocation	Feature 6.2
POST	/api/analyze/stagnant-deals	Feature 6.3
POST	/api/action-card/{id}/resolve	標記已處理
GET	/api/llm/models	LLM 模型列表
POST	/api/llm/chat	LLM 聊天

---

6. 配置

6.1 環境變數 (.env)

# Flask
FLASK_SECRET_KEY=xxx
FLASK_DEBUG=True

# Database
DB_HOST=mysql.theaken.com
DB_PORT=33306
DB_NAME=db_A102
DB_USER=A102
DB_PASSWORD=xxx

# Ollama
OLLAMA_API_URL=https://ollama_pjapi.theaken.com
OLLAMA_DEFAULT_MODEL=deepseek-reasoner
OLLAMA_ALT_MODEL=deepseek-chat

6.2 Table 命名規則

所有資料表以 DIT_C_ 為前綴

---

7. 部署

7.1 本地開發

pip install -r requirements.txt
python app.py 9000

存取 URL: http://127.0.0.1:9000/

注意: Port 5000/5001/8080 可能被其他服務占用，建議使用 9000

7.2 Production

• 使用 Gunicorn + Nginx
• 環境變數設定 FLASK_DEBUG=False
• 啟用 HTTPS

---

8. 版本歷史

版本	日期	變更
v1.0	2024-12-12	初始版本
v1.1	2025-12-12	LLM 模型更換為 deepseek-reasoner
v1.2	2025-12-12	新增 XLSX 檔案支援、修復 CSV 載入邏輯、SSL 憑證問題修復

---

9. 測試結果

9.1 功能測試 (2025-12-12)

測試項目	狀態	說明
Health Check	✅ PASS	/health 端點正常
Dashboard Page	✅ PASS	儀表板頁面載入正常
Upload Page	✅ PASS	上傳頁面載入正常
History Page	✅ PASS	歷史記錄頁面正常
LLM Connection	✅ PASS	deepseek-reasoner 連線正常
CSV Analysis	✅ PASS	CSV 分析功能正常
XLSX Support	✅ PASS	Excel 檔案支援正常

9.2 可用 LLM 模型

• deepseek-reasoner (預設)
• deepseek-chat (備用)
• gpt-oss:120b