937 lines
23 KiB
Markdown
937 lines
23 KiB
Markdown
# MES Dashboard - Architecture Findings
|
||
|
||
本文件記錄專案開發過程中確立的架構設計、全局規範與資料處理規則。
|
||
|
||
---
|
||
|
||
## 1. 資料庫連線管理
|
||
|
||
### 連線池統一使用
|
||
所有資料庫操作必須透過 `mes_dashboard.core.database` 模組：
|
||
|
||
```python
|
||
from mes_dashboard.core.database import read_sql_df, get_engine
|
||
|
||
# 讀取資料 (推薦方式)
|
||
df = read_sql_df(sql, params)
|
||
|
||
# 取得 engine（若需要直接操作）
|
||
engine = get_engine()
|
||
```
|
||
|
||
### 連線池配置 (位置: `core/database.py`)
|
||
|
||
| 參數 | 開發環境 | 生產環境 | 說明 |
|
||
|------|---------|---------|------|
|
||
| pool_size | 2 | 10 | 基礎連線數 |
|
||
| max_overflow | 3 | 20 | 額外連線數 |
|
||
| pool_timeout | 30 | 30 | 等待超時 (秒) |
|
||
| pool_recycle | 1800 | 1800 | 回收週期 (30分鐘) |
|
||
| pool_pre_ping | True | True | 使用前驗證連線 |
|
||
|
||
### Keep-Alive 機制
|
||
- 背景執行緒每 5 分鐘執行 `SELECT 1 FROM DUAL`
|
||
- 防止 NAT/防火牆斷開閒置連線
|
||
- 啟動: `start_keepalive()`，停止: `stop_keepalive()`
|
||
|
||
### 注意事項
|
||
- **禁止**在各 service 中自行建立連線
|
||
- **禁止**直接使用 `oracledb.connect()`
|
||
- 連線池由 `database.py` 統一管理，避免連線洩漏
|
||
- 測試環境需在 setUp 中重置：`db._ENGINE = None`
|
||
|
||
---
|
||
|
||
## 2. SQL 集中管理
|
||
|
||
### 目錄結構
|
||
所有 SQL 查詢放在 `src/mes_dashboard/sql/` 目錄：
|
||
|
||
```
|
||
sql/
|
||
├── loader.py # SQL 檔案載入器 (LRU 快取)
|
||
├── builder.py # 參數化查詢構建器
|
||
├── filters.py # 通用篩選條件
|
||
├── dashboard/ # 儀表板 SQL
|
||
│ ├── kpi.sql
|
||
│ ├── heatmap.sql
|
||
│ └── workcenter_cards.sql
|
||
├── wip/ # WIP SQL
|
||
│ ├── summary.sql
|
||
│ └── detail.sql
|
||
├── resource/ # 設備 SQL
|
||
│ ├── by_status.sql
|
||
│ └── detail.sql
|
||
├── resource_history/ # 歷史 SQL
|
||
└── job_query/ # 維修工單 SQL
|
||
```
|
||
|
||
### SQLLoader 使用方式
|
||
|
||
```python
|
||
from mes_dashboard.sql.loader import SQLLoader
|
||
|
||
# 載入 SQL 檔案 (自動 LRU 快取，最多 100 個)
|
||
sql = SQLLoader.load("wip/summary")
|
||
|
||
# 結構性參數替換 (用於 SQL 片段)
|
||
sql = SQLLoader.load_with_params("dashboard/kpi",
|
||
LATEST_STATUS_SUBQUERY="...",
|
||
WHERE_CLAUSE="...")
|
||
|
||
# 清除快取
|
||
SQLLoader.clear_cache()
|
||
```
|
||
|
||
### QueryBuilder 使用方式
|
||
|
||
```python
|
||
from mes_dashboard.sql.builder import QueryBuilder
|
||
|
||
builder = QueryBuilder()
|
||
|
||
# 添加條件 (自動參數化，防 SQL 注入)
|
||
builder.add_param_condition("STATUS", "PRD")
|
||
builder.add_in_condition("STATUS", ["PRD", "SBY"])
|
||
builder.add_not_in_condition("HOLD_REASON", exclude_list)
|
||
builder.add_like_condition("LOTID", user_input, position="both")
|
||
builder.add_or_like_conditions(["COL1", "COL2"], [val1, val2])
|
||
builder.add_is_null("COLUMN")
|
||
builder.add_is_not_null("COLUMN")
|
||
builder.add_condition("FIXED_CONDITION = 1") # 固定條件
|
||
|
||
# 構建 WHERE 子句
|
||
where_clause, params = builder.build_where_only()
|
||
|
||
# 替換佔位符並執行
|
||
sql = sql.replace("{{ WHERE_CLAUSE }}", where_clause)
|
||
df = read_sql_df(sql, params)
|
||
```
|
||
|
||
### 佔位符規範
|
||
|
||
| 類型 | 語法 | 用途 | 安全性 |
|
||
|------|------|------|--------|
|
||
| 結構性 | `{{ PLACEHOLDER }}` | 靜態 SQL 片段 | 僅限預定義值 |
|
||
| 參數 | `:param_name` | 動態用戶輸入 | Oracle bind variables |
|
||
|
||
### Oracle IN 子句限制
|
||
Oracle IN 子句上限 1000 個值，需分批處理：
|
||
|
||
```python
|
||
BATCH_SIZE = 1000
|
||
|
||
# 參考 job_query_service.py 的 _build_resource_filter()
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 快取機制
|
||
|
||
### 多層快取架構
|
||
|
||
```
|
||
請求 → 進程級快取 (30 秒 TTL)
|
||
→ Redis 快取 (可配置 TTL)
|
||
→ Oracle 資料庫
|
||
```
|
||
|
||
### 全局快取 API
|
||
使用 `mes_dashboard.core.cache` 模組：
|
||
|
||
```python
|
||
from mes_dashboard.core.cache import cache_get, cache_set, make_cache_key
|
||
|
||
# 建立快取 key（支援 filters dict）
|
||
cache_key = make_cache_key("resource_history_summary", filters={
|
||
'start_date': start_date,
|
||
'workcenter_groups': sorted(groups) if groups else None,
|
||
})
|
||
|
||
# 讀取/寫入快取
|
||
result = cache_get(cache_key)
|
||
if result is None:
|
||
result = query_data()
|
||
cache_set(cache_key, result, ttl=CACHE_TTL_TREND)
|
||
```
|
||
|
||
### 快取 TTL 常數
|
||
定義於 `mes_dashboard.config.constants`：
|
||
|
||
```python
|
||
CACHE_TTL_DEFAULT = 60 # 1 分鐘
|
||
CACHE_TTL_FILTER_OPTIONS = 600 # 10 分鐘
|
||
CACHE_TTL_PIVOT_COLUMNS = 300 # 5 分鐘
|
||
CACHE_TTL_KPI = 60 # 1 分鐘
|
||
CACHE_TTL_TREND = 300 # 5 分鐘
|
||
```
|
||
|
||
### Redis 快取配置
|
||
環境變數：
|
||
```
|
||
REDIS_ENABLED=true
|
||
REDIS_URL=redis://localhost:6379/0
|
||
REDIS_KEY_PREFIX=mes_wip
|
||
```
|
||
|
||
### 專用快取服務
|
||
|
||
| 服務 | 位置 | 用途 |
|
||
|------|------|------|
|
||
| WIP 快取更新器 | `core/cache_updater.py` | 背景線程自動更新 WIP 數據 |
|
||
| 資源快取 | `services/resource_cache.py` | DW_MES_RESOURCE 表快取 (4 小時同步) |
|
||
| 設備狀態快取 | `services/realtime_equipment_cache.py` | 設備實時狀態 (5 分鐘同步) |
|
||
| Filter 快取 | `services/filter_cache.py` | 篩選選項快取 |
|
||
|
||
---
|
||
|
||
## 4. Filter Cache（篩選選項快取）
|
||
|
||
### 位置
|
||
`mes_dashboard.services.filter_cache`
|
||
|
||
### 用途
|
||
快取全站共用的篩選選項，避免重複查詢資料庫：
|
||
|
||
```python
|
||
from mes_dashboard.services.filter_cache import (
|
||
get_workcenter_groups, # 取得 workcenter group 列表
|
||
get_workcenter_mapping, # 取得 workcentername → group 對應
|
||
get_workcenters_for_groups, # 根據 group 取得 workcentername 列表
|
||
get_resource_families, # 取得 resource family 列表
|
||
)
|
||
```
|
||
|
||
### Workcenter 對應關係
|
||
```
|
||
WORKCENTERNAME (資料庫) → WORKCENTER_GROUP (顯示)
|
||
焊接_DB_1 → 焊接_DB
|
||
焊接_DB_2 → 焊接_DB
|
||
成型_1 → 成型
|
||
```
|
||
|
||
### 資料來源
|
||
- Workcenter Groups: `DW_PJ_LOT_V` (WORKCENTER_GROUP, WORKCENTERSEQUENCE_GROUP)
|
||
- Resource Families: `DW_MES_RESOURCE` (RESOURCEFAMILYNAME)
|
||
|
||
---
|
||
|
||
## 5. 熔斷器 (Circuit Breaker)
|
||
|
||
### 位置
|
||
`mes_dashboard.core.circuit_breaker`
|
||
|
||
### 狀態機制
|
||
|
||
```
|
||
CLOSED (正常)
|
||
↓ 失敗達到閾值
|
||
OPEN (故障，拒絕請求)
|
||
↓ 等待 recovery_timeout
|
||
HALF_OPEN (測試恢復)
|
||
↓ 成功 → CLOSED / 失敗 → OPEN
|
||
```
|
||
|
||
### 配置 (環境變數)
|
||
|
||
```
|
||
CIRCUIT_BREAKER_ENABLED=true
|
||
CIRCUIT_BREAKER_FAILURE_THRESHOLD=5 # 最少失敗次數
|
||
CIRCUIT_BREAKER_FAILURE_RATE=0.5 # 失敗率閾值 (0.0-1.0)
|
||
CIRCUIT_BREAKER_RECOVERY_TIMEOUT=30 # OPEN 狀態等待秒數
|
||
CIRCUIT_BREAKER_WINDOW_SIZE=10 # 滑動窗口大小
|
||
```
|
||
|
||
### 使用方式
|
||
熔斷器已整合在 `read_sql_df()` 中，自動：
|
||
- 檢查是否允許請求
|
||
- 記錄成功/失敗
|
||
- 狀態轉移
|
||
|
||
### 狀態查詢
|
||
```python
|
||
from mes_dashboard.core.circuit_breaker import get_database_circuit_breaker
|
||
|
||
cb = get_database_circuit_breaker()
|
||
status = cb.get_status()
|
||
# status.state, status.failure_count, status.success_count, status.failure_rate
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 統一 API 響應格式
|
||
|
||
### 位置
|
||
`mes_dashboard.core.response`
|
||
|
||
### 響應格式
|
||
|
||
```python
|
||
# 成功響應
|
||
{
|
||
"success": True,
|
||
"data": {...},
|
||
"meta": {"timestamp": "2024-02-04T10:30:45.123456"}
|
||
}
|
||
|
||
# 錯誤響應
|
||
{
|
||
"success": False,
|
||
"error": {
|
||
"code": "DB_CONNECTION_FAILED",
|
||
"message": "資料庫連線失敗，請稍後再試",
|
||
"details": "ORA-12541" # 僅開發模式
|
||
},
|
||
"meta": {"timestamp": "..."}
|
||
}
|
||
```
|
||
|
||
### 錯誤代碼
|
||
|
||
| 代碼 | HTTP | 說明 |
|
||
|------|------|------|
|
||
| DB_CONNECTION_FAILED | 503 | 資料庫連線失敗 |
|
||
| DB_QUERY_TIMEOUT | 504 | 查詢逾時 |
|
||
| DB_QUERY_ERROR | 500 | 查詢執行錯誤 |
|
||
| SERVICE_UNAVAILABLE | 503 | 服務不可用 |
|
||
| CIRCUIT_BREAKER_OPEN | 503 | 熔斷器開啟 |
|
||
| VALIDATION_ERROR | 400 | 驗證失敗 |
|
||
| UNAUTHORIZED | 401 | 未授權 |
|
||
| FORBIDDEN | 403 | 禁止訪問 |
|
||
| NOT_FOUND | 404 | 不存在 |
|
||
| TOO_MANY_REQUESTS | 429 | 過多請求 |
|
||
| INTERNAL_ERROR | 500 | 內部錯誤 |
|
||
|
||
### 便利函數
|
||
|
||
```python
|
||
from mes_dashboard.core.response import (
|
||
success_response,
|
||
validation_error, # 400
|
||
unauthorized_error, # 401
|
||
forbidden_error, # 403
|
||
not_found_error, # 404
|
||
db_connection_error, # 503
|
||
internal_error, # 500
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 認證與授權機制
|
||
|
||
### 認證服務
|
||
位置: `mes_dashboard.services.auth_service`
|
||
|
||
#### LDAP 認證 (生產環境)
|
||
```python
|
||
from mes_dashboard.services.auth_service import authenticate
|
||
|
||
user = authenticate(username, password)
|
||
# 返回: {username, displayName, mail, department}
|
||
```
|
||
|
||
#### 本地認證 (開發環境)
|
||
```
|
||
LOCAL_AUTH_ENABLED=true
|
||
LOCAL_AUTH_USERNAME=admin
|
||
LOCAL_AUTH_PASSWORD=password
|
||
```
|
||
|
||
### Session 管理
|
||
```python
|
||
# 登入後存入 session
|
||
session["admin"] = {
|
||
"username": user.get("username"),
|
||
"displayName": user.get("displayName"),
|
||
"mail": user.get("mail"),
|
||
"department": user.get("department"),
|
||
"login_time": datetime.now().isoformat()
|
||
}
|
||
|
||
# Session 配置
|
||
SESSION_COOKIE_SECURE = True # HTTPS only (生產)
|
||
SESSION_COOKIE_HTTPONLY = True # 防止 JS 訪問
|
||
SESSION_COOKIE_SAMESITE = 'Lax' # CSRF 防護
|
||
PERMANENT_SESSION_LIFETIME = 28800 # 8 小時
|
||
```
|
||
|
||
### 權限檢查
|
||
位置: `mes_dashboard.core.permissions`
|
||
|
||
```python
|
||
from mes_dashboard.core.permissions import is_admin_logged_in, admin_required
|
||
|
||
# 檢查登入狀態
|
||
if is_admin_logged_in():
|
||
...
|
||
|
||
# 裝飾器保護路由
|
||
@admin_required
|
||
def admin_only_view():
|
||
...
|
||
```
|
||
|
||
### 登入速率限制
|
||
- 單 IP 每 5 分鐘最多 5 次嘗試
|
||
- 位置: `routes/auth_routes.py`
|
||
|
||
---
|
||
|
||
## 8. 頁面狀態管理
|
||
|
||
### 位置
|
||
- 服務: `mes_dashboard.services.page_registry`
|
||
- 數據: `data/page_status.json`
|
||
|
||
### 狀態定義
|
||
|
||
| 狀態 | 說明 |
|
||
|------|------|
|
||
| `released` | 所有用戶可訪問 |
|
||
| `dev` | 僅管理員可訪問 |
|
||
| `None` | 未註冊，由 Flask 路由控制 |
|
||
|
||
### 數據格式
|
||
```json
|
||
{
|
||
"pages": [
|
||
{"route": "/wip-overview", "name": "WIP 即時概況", "status": "released"},
|
||
{"route": "/tables", "name": "表格總覽", "status": "dev"}
|
||
],
|
||
"api_public": true
|
||
}
|
||
```
|
||
|
||
### API
|
||
|
||
```python
|
||
from mes_dashboard.services.page_registry import (
|
||
get_page_status, # 取得頁面狀態
|
||
set_page_status, # 設定頁面狀態
|
||
is_api_public, # API 是否公開
|
||
get_all_pages, # 取得所有頁面
|
||
)
|
||
```
|
||
|
||
### 權限檢查 (自動)
|
||
在 `app.py` 的 `@app.before_request` 中自動執行：
|
||
- dev 頁面 + 非管理員 → 403
|
||
|
||
---
|
||
|
||
## 9. 日誌系統
|
||
|
||
### 雙層日誌架構
|
||
|
||
| 層級 | 目標 | 用途 |
|
||
|------|------|------|
|
||
| 控制台 (stderr) | Gunicorn 捕獲 | 即時監控 |
|
||
| SQLite | 管理員儀表板 | 歷史查詢 |
|
||
|
||
### 配置 (環境變數)
|
||
```
|
||
LOG_STORE_ENABLED=true
|
||
LOG_SQLITE_PATH=logs/admin_logs.sqlite
|
||
LOG_SQLITE_RETENTION_DAYS=7
|
||
LOG_SQLITE_MAX_ROWS=100000
|
||
```
|
||
|
||
### 日誌記錄規範
|
||
|
||
```python
|
||
import logging
|
||
logger = logging.getLogger('mes_dashboard')
|
||
|
||
logger.debug("詳細調試資訊")
|
||
logger.info("一般操作記錄")
|
||
logger.warning("警告但可繼續")
|
||
logger.error("錯誤需要關注", exc_info=True) # 包含堆棧
|
||
```
|
||
|
||
### SQLite 日誌查詢
|
||
位置: `mes_dashboard.core.log_store`
|
||
|
||
```python
|
||
from mes_dashboard.core.log_store import get_log_store
|
||
|
||
store = get_log_store()
|
||
logs = store.query_logs(
|
||
level="ERROR",
|
||
limit=100,
|
||
offset=0,
|
||
search="keyword"
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## 10. 健康檢查
|
||
|
||
### 端點
|
||
|
||
| 端點 | 認證 | 說明 |
|
||
|------|------|------|
|
||
| `/health` | 無需 | 基本健康檢查 |
|
||
| `/health/deep` | 需管理員 | 詳細指標 |
|
||
|
||
### 基本檢查項目
|
||
- 資料庫連線 (`SELECT 1 FROM DUAL`)
|
||
- Redis 連線 (`PING`)
|
||
- 各快取狀態
|
||
|
||
### 詳細檢查項目 (deep)
|
||
- 資料庫延遲 (毫秒)
|
||
- 連線池狀態 (size, checked_out, overflow)
|
||
- 快取新鮮度
|
||
- 熔斷器狀態
|
||
- 查詢性能指標 (P50/P95/P99)
|
||
|
||
### 狀態判定
|
||
- `200 OK` (healthy/degraded): DB 正常
|
||
- `503 Unavailable` (unhealthy): DB 故障
|
||
|
||
---
|
||
|
||
## 11. API 路由結構 (Blueprint)
|
||
|
||
### Blueprint 列表
|
||
|
||
| Blueprint | URL 前綴 | 檔案 |
|
||
|-----------|---------|------|
|
||
| wip | `/api/wip` | `wip_routes.py` |
|
||
| resource | `/api/resource` | `resource_routes.py` |
|
||
| dashboard | `/api/dashboard` | `dashboard_routes.py` |
|
||
| excel_query | `/api/excel-query` | `excel_query_routes.py` |
|
||
| hold | `/api/hold` | `hold_routes.py` |
|
||
| resource_history | `/api/resource-history` | `resource_history_routes.py` |
|
||
| job_query | `/api/job-query` | `job_query_routes.py` |
|
||
| admin | `/admin` | `admin_routes.py` |
|
||
| auth | `/admin` | `auth_routes.py` |
|
||
| health | `/` | `health_routes.py` |
|
||
|
||
### 路由註冊
|
||
位置: `routes/__init__.py` 的 `register_routes(app)`
|
||
|
||
---
|
||
|
||
## 12. 前端全局組件
|
||
|
||
### Toast 通知
|
||
定義於 `static/js/toast.js`，透過 `_base.html` 載入：
|
||
|
||
```javascript
|
||
// 正確用法
|
||
Toast.info('訊息');
|
||
Toast.success('成功');
|
||
Toast.warning('警告');
|
||
Toast.error('錯誤', { retry: () => loadData() });
|
||
|
||
const id = Toast.loading('載入中...');
|
||
Toast.update(id, { message: '完成!' });
|
||
Toast.dismiss(id);
|
||
|
||
// 錯誤用法（不存在）
|
||
MESToast.warning('...'); // ❌ 錯誤
|
||
```
|
||
|
||
### 自動消失時間
|
||
- info: 3000ms
|
||
- success: 2000ms
|
||
- warning: 5000ms
|
||
- error: 永久（需手動關閉）
|
||
- loading: 永久
|
||
|
||
### MesApi（HTTP 請求）
|
||
定義於 `static/js/mes-api.js`：
|
||
|
||
```javascript
|
||
// GET 請求
|
||
const data = await MesApi.get('/api/wip/summary', {
|
||
params: { page: 1 },
|
||
timeout: 60000,
|
||
retries: 5,
|
||
signal: abortController.signal,
|
||
silent: true // 禁用 toast 通知
|
||
});
|
||
|
||
// POST 請求
|
||
const data = await MesApi.post('/api/query_table', {
|
||
table_name: 'TABLE_A',
|
||
filters: {...}
|
||
});
|
||
```
|
||
|
||
### MesApi 特性
|
||
- 自動重試 (3 次，指數退避: 1s, 2s, 4s)
|
||
- 自動 Toast 通知
|
||
- 請求 ID 追蹤
|
||
- AbortSignal 支援
|
||
- 4xx 不重試，5xx 重試
|
||
|
||
---
|
||
|
||
## 13. 資料表預篩選規則
|
||
|
||
### 設備類型篩選
|
||
定義於 `mes_dashboard.config.constants.EQUIPMENT_TYPE_FILTER`：
|
||
|
||
```sql
|
||
((OBJECTCATEGORY = 'ASSEMBLY' AND OBJECTTYPE = 'ASSEMBLY')
|
||
OR (OBJECTCATEGORY = 'WAFERSORT' AND OBJECTTYPE = 'WAFERSORT'))
|
||
```
|
||
|
||
### 排除條件
|
||
```python
|
||
# 排除的地點
|
||
EXCLUDED_LOCATIONS = [
|
||
'ATEC', 'F區', 'F區焊接站', '報廢', '實驗室',
|
||
'山東', '成型站_F區', '焊接F區', '無錫', '熒茂'
|
||
]
|
||
|
||
# 排除的資產狀態
|
||
EXCLUDED_ASSET_STATUSES = ['Disapproved']
|
||
```
|
||
|
||
### CommonFilters 使用
|
||
位置: `mes_dashboard.sql.filters`
|
||
|
||
```python
|
||
from mes_dashboard.sql.filters import CommonFilters
|
||
|
||
# 添加標準篩選
|
||
CommonFilters.add_location_exclusion(builder, 'r')
|
||
CommonFilters.add_asset_status_exclusion(builder, 'r')
|
||
CommonFilters.add_wip_base_filters(builder, filters)
|
||
CommonFilters.add_equipment_filter(builder, filters)
|
||
```
|
||
|
||
---
|
||
|
||
## 14. 資料庫欄位對應
|
||
|
||
### DW_MES_RESOURCE
|
||
| 常見錯誤 | 正確欄位名 |
|
||
|---------|-----------|
|
||
| ASSETSTATUS | PJ_ASSETSSTATUS（雙 S）|
|
||
| LOCATION | LOCATIONNAME |
|
||
| ISPRODUCTION | PJ_ISPRODUCTION |
|
||
| ISKEY | PJ_ISKEY |
|
||
| ISMONITOR | PJ_ISMONITOR |
|
||
|
||
### DW_MES_RESOURCESTATUS_SHIFT
|
||
| 欄位 | 說明 |
|
||
|-----|------|
|
||
| HISTORYID | 對應 DW_MES_RESOURCE.RESOURCEID |
|
||
| TXNDATE | 交易日期 |
|
||
| OLDSTATUSNAME | E10 狀態 (PRD, SBY, UDT, SDT, EGT, NST) |
|
||
| HOURS | 該狀態時數 |
|
||
|
||
### DW_PJ_LOT_V
|
||
| 欄位 | 說明 |
|
||
|-----|------|
|
||
| WORKCENTERNAME | 站點名稱（細分）|
|
||
| WORKCENTER_GROUP | 站點群組（顯示用）|
|
||
| WORKCENTERSEQUENCE_GROUP | 群組排序 |
|
||
|
||
---
|
||
|
||
## 15. E10 狀態定義
|
||
|
||
| 狀態 | 說明 | 計入 OU% |
|
||
|-----|------|---------|
|
||
| PRD | Production（生產）| 是（分子）|
|
||
| SBY | Standby（待機）| 是（分母）|
|
||
| UDT | Unscheduled Downtime（非計畫停機）| 是（分母）|
|
||
| SDT | Scheduled Downtime（計畫停機）| 是（分母）|
|
||
| EGT | Engineering Time（工程時間）| 是（分母）|
|
||
| NST | Non-Scheduled Time（非排程時間）| 否 |
|
||
|
||
### OU% 計算公式
|
||
```
|
||
OU% = PRD / (PRD + SBY + UDT + SDT + EGT) × 100
|
||
```
|
||
|
||
### 狀態顯示名稱
|
||
```python
|
||
STATUS_DISPLAY_NAMES = {
|
||
'PRD': '生產中',
|
||
'SBY': '待機',
|
||
'UDT': '非計畫停機',
|
||
'SDT': '計畫停機',
|
||
'EGT': '工程時間',
|
||
'NST': '未排單',
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 16. 配置管理
|
||
|
||
### 環境變數 (.env)
|
||
|
||
#### 資料庫
|
||
```
|
||
DB_HOST=<your_database_host>
|
||
DB_PORT=1521
|
||
DB_SERVICE=<your_service_name>
|
||
DB_USER=<your_username>
|
||
DB_PASSWORD=<your_password>
|
||
DB_POOL_SIZE=5
|
||
DB_MAX_OVERFLOW=10
|
||
```
|
||
|
||
> 實際值請參考 `.env` 或 `.env.example`
|
||
|
||
#### Flask
|
||
```
|
||
FLASK_ENV=production
|
||
FLASK_DEBUG=0
|
||
SECRET_KEY=your_secret_key
|
||
SESSION_LIFETIME=28800
|
||
```
|
||
|
||
#### 認證
|
||
```
|
||
LDAP_API_URL=<your_ldap_api_url>
|
||
ADMIN_EMAILS=<admin_email_list>
|
||
LOCAL_AUTH_ENABLED=false
|
||
```
|
||
|
||
#### Gunicorn
|
||
```
|
||
GUNICORN_BIND=0.0.0.0:8080
|
||
GUNICORN_WORKERS=4
|
||
GUNICORN_THREADS=8
|
||
```
|
||
|
||
#### 快取
|
||
```
|
||
REDIS_ENABLED=true
|
||
REDIS_URL=redis://localhost:6379/0
|
||
CACHE_CHECK_INTERVAL=600
|
||
RESOURCE_CACHE_ENABLED=true
|
||
RESOURCE_SYNC_INTERVAL=14400
|
||
```
|
||
|
||
#### 熔斷器
|
||
```
|
||
CIRCUIT_BREAKER_ENABLED=true
|
||
CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
|
||
CIRCUIT_BREAKER_FAILURE_RATE=0.5
|
||
CIRCUIT_BREAKER_RECOVERY_TIMEOUT=30
|
||
```
|
||
|
||
#### 日誌
|
||
```
|
||
LOG_STORE_ENABLED=true
|
||
LOG_SQLITE_PATH=logs/admin_logs.sqlite
|
||
LOG_SQLITE_RETENTION_DAYS=7
|
||
```
|
||
|
||
### 環境配置類
|
||
位置: `mes_dashboard.config.settings`
|
||
|
||
```python
|
||
class DevelopmentConfig(Config):
|
||
DEBUG = True
|
||
DB_POOL_SIZE = 2
|
||
|
||
class ProductionConfig(Config):
|
||
DEBUG = False
|
||
DB_POOL_SIZE = 10
|
||
|
||
class TestingConfig(Config):
|
||
TESTING = True
|
||
DB_POOL_SIZE = 1
|
||
```
|
||
|
||
---
|
||
|
||
## 17. 平行查詢
|
||
|
||
### ThreadPoolExecutor
|
||
對於多個獨立查詢，使用平行執行提升效能：
|
||
|
||
```python
|
||
from concurrent.futures import ThreadPoolExecutor, as_completed
|
||
|
||
with ThreadPoolExecutor(max_workers=4) as executor:
|
||
futures = {
|
||
executor.submit(read_sql_df, kpi_sql): 'kpi',
|
||
executor.submit(read_sql_df, trend_sql): 'trend',
|
||
executor.submit(read_sql_df, heatmap_sql): 'heatmap',
|
||
}
|
||
for future in as_completed(futures):
|
||
query_name = futures[future]
|
||
results[query_name] = future.result()
|
||
```
|
||
|
||
### 注意事項
|
||
- Mock 測試時不能使用 `side_effect` 列表（順序不可預測）
|
||
- 應使用函式判斷 SQL 內容來回傳對應的 mock 資料
|
||
|
||
---
|
||
|
||
## 18. Oracle SQL 優化
|
||
|
||
### CTE MATERIALIZE Hint
|
||
防止 Oracle 優化器將 CTE inline 多次執行：
|
||
|
||
```sql
|
||
WITH shift_data AS (
|
||
SELECT /*+ MATERIALIZE */ HISTORYID, TXNDATE, OLDSTATUSNAME, HOURS
|
||
FROM DW_MES_RESOURCESTATUS_SHIFT
|
||
WHERE TXNDATE >= TO_DATE('2024-01-01', 'YYYY-MM-DD')
|
||
AND TXNDATE < TO_DATE('2024-01-07', 'YYYY-MM-DD') + 1
|
||
)
|
||
SELECT ...
|
||
```
|
||
|
||
### 日期範圍查詢
|
||
```sql
|
||
-- 包含 end_date 當天
|
||
WHERE TXNDATE >= TO_DATE(:start_date, 'YYYY-MM-DD')
|
||
AND TXNDATE < TO_DATE(:end_date, 'YYYY-MM-DD') + 1
|
||
```
|
||
|
||
### 慢查詢警告
|
||
- 閾值: 1 秒 (警告)，5 秒 (`SLOW_QUERY_THRESHOLD`)
|
||
- 自動記錄到日誌
|
||
|
||
---
|
||
|
||
## 19. 前端資料限制
|
||
|
||
### 明細資料上限
|
||
為避免瀏覽器記憶體問題，明細查詢有筆數限制：
|
||
|
||
```python
|
||
MAX_DETAIL_RECORDS = 5000
|
||
|
||
if total > MAX_DETAIL_RECORDS:
|
||
df = df.head(MAX_DETAIL_RECORDS)
|
||
truncated = True
|
||
```
|
||
|
||
前端顯示警告：
|
||
```javascript
|
||
if (result.truncated) {
|
||
Toast.warning(`資料超過 ${result.max_records} 筆，請使用篩選條件縮小範圍。`);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 20. JavaScript 注意事項
|
||
|
||
### Array.reverse() 原地修改
|
||
```javascript
|
||
// 錯誤 - 原地修改陣列
|
||
const arr = [1, 2, 3];
|
||
arr.reverse(); // arr 被修改為 [3, 2, 1]
|
||
|
||
// 正確 - 建立新陣列
|
||
const reversed = arr.slice().reverse(); // arr 不變
|
||
// 或
|
||
const reversed = [...arr].reverse();
|
||
```
|
||
|
||
---
|
||
|
||
## 21. 測試規範
|
||
|
||
### 測試檔案結構
|
||
```
|
||
tests/
|
||
├── conftest.py # pytest fixtures
|
||
├── test_*_service.py # 單元測試（service layer）
|
||
├── test_*_routes.py # 整合測試（API endpoints）
|
||
├── e2e/
|
||
│ └── test_*_e2e.py # 端對端測試（完整流程）
|
||
└── stress/
|
||
└── test_*.py # 壓力測試
|
||
```
|
||
|
||
### 測試前重置
|
||
```python
|
||
def setUp(self):
|
||
db._ENGINE = None # 重置連線池
|
||
self.app = create_app('testing')
|
||
```
|
||
|
||
### 執行測試
|
||
```bash
|
||
# 單一模組
|
||
pytest tests/test_resource_history_service.py -v
|
||
|
||
# 全部相關測試
|
||
pytest tests/test_resource_history_*.py tests/e2e/test_resource_history_e2e.py -v
|
||
|
||
# 覆蓋率報告
|
||
pytest tests/ --cov=mes_dashboard
|
||
```
|
||
|
||
---
|
||
|
||
## 22. 錯誤處理模式
|
||
|
||
### 三層錯誤處理
|
||
|
||
```python
|
||
# 1. 路由層 - 驗證錯誤
|
||
@bp.route('/api/query')
|
||
def query():
|
||
if not request.json.get('table_name'):
|
||
return validation_error("table_name 為必填")
|
||
|
||
# 2. 服務層 - 業務錯誤 (優雅降級)
|
||
def get_wip_summary(filters):
|
||
try:
|
||
df = query_wip(filters)
|
||
if df.empty:
|
||
return None
|
||
return process_data(df)
|
||
except Exception as exc:
|
||
logger.error(f"WIP query failed: {exc}")
|
||
return None
|
||
|
||
# 3. 核心層 - 基礎設施錯誤
|
||
def read_sql_df(sql, params):
|
||
if not circuit_breaker.allow_request():
|
||
raise RuntimeError("Circuit breaker open")
|
||
```
|
||
|
||
### 全局錯誤處理
|
||
位置: `app.py` 的 `_register_error_handlers()`
|
||
|
||
- 401 → `unauthorized_error()`
|
||
- 403 → `forbidden_error()`
|
||
- 404 → JSON (API) 或 HTML (頁面)
|
||
- 500 → `internal_error()`
|
||
- Exception → 通用處理
|
||
|
||
---
|
||
|
||
## 參考檔案索引
|
||
|
||
| 功能 | 檔案位置 |
|
||
|------|---------|
|
||
| SQL 載入 | `src/mes_dashboard/sql/loader.py` |
|
||
| 查詢構建 | `src/mes_dashboard/sql/builder.py` |
|
||
| 通用篩選 | `src/mes_dashboard/sql/filters.py` |
|
||
| 資料庫操作 | `src/mes_dashboard/core/database.py` |
|
||
| 快取 | `src/mes_dashboard/core/cache.py` |
|
||
| 熔斷器 | `src/mes_dashboard/core/circuit_breaker.py` |
|
||
| API 響應 | `src/mes_dashboard/core/response.py` |
|
||
| 權限檢查 | `src/mes_dashboard/core/permissions.py` |
|
||
| 日誌存儲 | `src/mes_dashboard/core/log_store.py` |
|
||
| 配置類 | `src/mes_dashboard/config/settings.py` |
|
||
| 常量定義 | `src/mes_dashboard/config/constants.py` |
|
||
| 認證服務 | `src/mes_dashboard/services/auth_service.py` |
|
||
| 頁面狀態 | `src/mes_dashboard/services/page_registry.py` |
|
||
| Filter 快取 | `src/mes_dashboard/services/filter_cache.py` |
|
||
| 資源快取 | `src/mes_dashboard/services/resource_cache.py` |
|
||
| API 客戶端 | `src/mes_dashboard/static/js/mes-api.js` |
|
||
| Toast 系統 | `src/mes_dashboard/static/js/toast.js` |
|