taiwan-logistics-skill 1.0.0

package/assets/taiwan-logistics/scripts/core.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+"""
+Taiwan Logistics BM25 搜索引擎
+
+基於 BM25 (Okapi BM25) 演算法的語義搜索系統
+支援多個搜索域: provider, operation, logistics_type, field, status
+
+用法:
+    from core import search, search_all, detect_domain
+
+    # 單域搜索
+    results = search("7-11", domain="logistics_type", max_results=5)
+
+    # 自動偵測域
+    results = search("NewebPay API", domain=None, max_results=3)
+
+    # 全域搜索
+    all_results = search_all("配送失敗", max_per_domain=3)
+"""
+
+import csv
+import math
+import re
+from pathlib import Path
+from typing import List, Dict, Optional, Tuple
+import json
+
+# 數據文件路徑
+SCRIPT_DIR = Path(__file__).parent
+DATA_DIR = SCRIPT_DIR.parent / 'data'
+
+# CSV 配置
+CSV_CONFIG = {
+    'provider': {
+        'file': 'providers.csv',
+        'search_cols': ['provider', 'name_zh', 'name_en', 'features'],
+        'output_cols': ['provider', 'name_zh', 'type', 'test_merchant_id', 'test_hash_key', 'features', 'coverage']
+    },
+    'operation': {
+        'file': 'operations.csv',
+        'search_cols': ['operation', 'operation_zh', 'ecpay_endpoint', 'required_fields', 'notes'],
+        'output_cols': ['operation', 'operation_zh', 'ecpay_endpoint', 'method', 'required_fields', 'optional_fields', 'notes']
+    },
+    'logistics_type': {
+        'file': 'logistics-types.csv',
+        'search_cols': ['code', 'name_zh', 'name_en', 'provider', 'notes'],
+        'output_cols': ['code', 'name_zh', 'provider', 'category', 'size_limit', 'weight_limit', 'notes']
+    },
+    'field': {
+        'file': 'field-mappings.csv',
+        'search_cols': ['field_name', 'field_zh', 'ecpay_name', 'newebpay_name', 'payuni_name', 'notes'],
+        'output_cols': ['field_name', 'field_zh', 'ecpay_name', 'newebpay_name', 'payuni_name', 'type', 'required', 'format', 'notes']
+    },
+    'status': {
+        'file': 'status-codes.csv',
+        'search_cols': ['provider', 'code', 'status_zh', 'status_en', 'description'],
+        'output_cols': ['provider', 'code', 'status_zh', 'category', 'description']
+    }
+}
+
+# 域偵測關鍵字
+DOMAIN_KEYWORDS = {
+    'provider': ['ecpay', '綠界', 'newebpay', '藍新', 'payuni', '統一', '物流', '服務商', 'provider'],
+    'operation': ['create', 'query', 'print', 'map', '建立', '查詢', '列印', '電子地圖', 'api', 'endpoint'],
+    'logistics_type': ['711', '7-11', 'family', '全家', 'hilife', '萊爾富', 'okmart', 'tcat', '黑貓', '超商', '宅配', 'cvs', 'home'],
+    'field': ['field', 'parameter', '參數', '欄位', 'merchantid', 'tradeno', 'logistics'],
+    'status': ['status', 'code', '狀態', '配送', '取貨', '完成', '失敗', '300', '3001']
+}
+
+
+def tokenize(text: str) -> List[str]:
+    """中英文混合分詞"""
+    if not text:
+        return []
+
+    # 轉小寫
+    text = text.lower()
+
+    # 分離中英文
+    tokens = []
+
+    # 英文 token (包含數字)
+    for match in re.finditer(r'[a-z0-9]+', text):
+        tokens.append(match.group())
+
+    # 中文 bigram + unigram
+    chinese_chars = re.findall(r'[\u4e00-\u9fff]', text)
+    for char in chinese_chars:
+        tokens.append(char)
+
+    # Bigram for better matching
+    for i in range(len(chinese_chars) - 1):
+        tokens.append(chinese_chars[i] + chinese_chars[i + 1])
+
+    return tokens
+
+
+def compute_idf(documents: List[List[str]]) -> Dict[str, float]:
+    """計算 IDF (Inverse Document Frequency)"""
+    n = len(documents)
+    df = {}
+
+    for doc in documents:
+        seen = set()
+        for term in doc:
+            if term not in seen:
+                df[term] = df.get(term, 0) + 1
+                seen.add(term)
+
+    idf = {}
+    for term, freq in df.items():
+        idf[term] = math.log((n - freq + 0.5) / (freq + 0.5) + 1.0)
+
+    return idf
+
+
+def bm25_score(
+    query_tokens: List[str],
+    doc_tokens: List[str],
+    idf: Dict[str, float],
+    avg_dl: float,
+    k1: float = 1.5,
+    b: float = 0.75
+) -> float:
+    """計算 BM25 分數"""
+    score = 0.0
+    dl = len(doc_tokens)
+
+    # Term frequency in document
+    tf = {}
+    for term in doc_tokens:
+        tf[term] = tf.get(term, 0) + 1
+
+    for term in query_tokens:
+        if term in tf:
+            freq = tf[term]
+            idf_score = idf.get(term, 0)
+            numerator = freq * (k1 + 1)
+            denominator = freq + k1 * (1 - b + b * (dl / avg_dl))
+            score += idf_score * (numerator / denominator)
+
+    return score
+
+
+def load_csv(domain: str) -> Tuple[List[Dict], List[List[str]]]:
+    """載入 CSV 並返回行數據和 token 化文檔"""
+    config = CSV_CONFIG.get(domain)
+    if not config:
+        return [], []
+
+    csv_path = DATA_DIR / config['file']
+    if not csv_path.exists():
+        return [], []
+
+    rows = []
+    documents = []
+
+    with open(csv_path, 'r', encoding='utf-8') as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            rows.append(row)
+
+            # 組合搜索欄位
+            search_text = ' '.join(
+                str(row.get(col, '')) for col in config['search_cols']
+            )
+            documents.append(tokenize(search_text))
+
+    return rows, documents
+
+
+def detect_domain(query: str) -> str:
+    """自動偵測查詢應該屬於哪個域"""
+    query_lower = query.lower()
+    scores = {}
+
+    for domain, keywords in DOMAIN_KEYWORDS.items():
+        score = sum(1 for kw in keywords if kw in query_lower)
+        scores[domain] = score
+
+    # 返回最高分的域，如果都是 0 則返回 'provider'
+    max_score = max(scores.values())
+    if max_score == 0:
+        return 'provider'
+
+    return max(scores, key=scores.get)
+
+
+def search(
+    query: str,
+    domain: Optional[str] = None,
+    max_results: int = 5
+) -> List[Dict]:
+    """
+    主搜索函數
+
+    Args:
+        query: 搜索查詢
+        domain: 搜索域 (None 表示自動偵測)
+        max_results: 最大結果數
+
+    Returns:
+        結果列表 (按分數排序)
+    """
+    if not query:
+        return []
+
+    # 自動偵測域
+    if domain is None:
+        domain = detect_domain(query)
+
+    # 載入數據
+    rows, documents = load_csv(domain)
+    if not rows:
+        return []
+
+    # 計算 IDF
+    idf = compute_idf(documents)
+    avg_dl = sum(len(doc) for doc in documents) / len(documents)
+
+    # Query tokens
+    query_tokens = tokenize(query)
+
+    # 計算每個文檔的分數
+    scores = []
+    for i, doc_tokens in enumerate(documents):
+        score = bm25_score(query_tokens, doc_tokens, idf, avg_dl)
+        if score > 0:
+            scores.append((score, i))
+
+    # 排序並返回結果
+    scores.sort(reverse=True)
+
+    config = CSV_CONFIG[domain]
+    results = []
+
+    for score, idx in scores[:max_results]:
+        row = rows[idx]
+        result = {col: row.get(col, '') for col in config['output_cols']}
+        result['_score'] = round(score, 2)
+        result['_domain'] = domain
+        results.append(result)
+
+    return results
+
+
+def search_all(query: str, max_per_domain: int = 3) -> Dict[str, List]:
+    """全域搜索 (搜索所有域)"""
+    all_results = {}
+
+    for domain in CSV_CONFIG.keys():
+        results = search(query, domain=domain, max_results=max_per_domain)
+        if results:
+            all_results[domain] = results
+
+    return all_results
+
+
+if __name__ == '__main__':
+    # 測試
+    import sys
+
+    if len(sys.argv) < 2:
+        print("用法: python core.py <query> [domain]")
+        print(f"可用域: {', '.join(CSV_CONFIG.keys())}")
+        sys.exit(1)
+
+    query = sys.argv[1]
+    domain = sys.argv[2] if len(sys.argv) > 2 else None
+
+    if domain == 'all':
+        results = search_all(query)
+        print(json.dumps(results, ensure_ascii=False, indent=2))
+    else:
+        results = search(query, domain=domain)
+        print(json.dumps(results, ensure_ascii=False, indent=2))

package/assets/taiwan-logistics/scripts/search.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""
+Taiwan Logistics 搜索命令行工具
+
+用法:
+    python search.py "7-11"                     # 自動偵測域
+    python search.py "建立訂單" --domain operation  # 指定域
+    python search.py "配送狀態" --format json    # JSON 輸出
+    python search.py "NewebPay" --max 10        # 限制結果數量
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Add parent directory to path
+SCRIPT_DIR = Path(__file__).parent
+sys.path.insert(0, str(SCRIPT_DIR))
+
+from core import search, search_all, detect_domain, CSV_CONFIG
+
+
+def format_text(results: list) -> str:
+    """格式化為文本輸出"""
+    if not results:
+        return "沒有找到結果"
+
+    output = []
+    for i, result in enumerate(results, 1):
+        domain = result.pop('_domain', 'unknown')
+        score = result.pop('_score', 0)
+
+        output.append(f"\n[{i}] 分數: {score:.2f} | 域: {domain}")
+        output.append("-" * 60)
+
+        for key, value in result.items():
+            if value:
+                output.append(f"  {key}: {value}")
+
+    return "\n".join(output)
+
+
+def format_json(results: list) -> str:
+    """格式化為 JSON 輸出"""
+    return json.dumps(results, ensure_ascii=False, indent=2)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Taiwan Logistics 搜索工具',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+範例:
+  %(prog)s "7-11 取貨"                    # 搜索 7-11 相關
+  %(prog)s "NewebPay" --domain provider  # 搜索服務商
+  %(prog)s "建立訂單" --domain operation  # 搜索 API 操作
+  %(prog)s "配送中" --domain status      # 搜索配送狀態
+  %(prog)s "重量" --domain field         # 搜索欄位說明
+  %(prog)s "黑貓" --format json          # JSON 輸出
+
+可用域 (domains):
+  provider       - 物流服務商 (ECPay, NewebPay, PAYUNi)
+  operation      - API 操作 (建立、查詢、列印)
+  logistics_type - 物流類型 (7-11, 全家, 黑貓)
+  field          - 欄位對照表
+  status         - 配送狀態碼
+  all            - 全域搜索
+        """
+    )
+
+    parser.add_argument(
+        'query',
+        help='搜索關鍵字'
+    )
+    parser.add_argument(
+        '--domain', '-d',
+        choices=list(CSV_CONFIG.keys()) + ['all'],
+        help='搜索域 (不指定則自動偵測)'
+    )
+    parser.add_argument(
+        '--max', '-m',
+        type=int,
+        default=5,
+        metavar='N',
+        help='最大結果數量 (預設: 5)'
+    )
+    parser.add_argument(
+        '--format', '-f',
+        choices=['text', 'json'],
+        default='text',
+        help='輸出格式 (預設: text)'
+    )
+
+    args = parser.parse_args()
+
+    # 執行搜索
+    if args.domain == 'all':
+        results = search_all(args.query, max_per_domain=args.max)
+
+        if args.format == 'json':
+            print(format_json(results))
+        else:
+            print(f"\n搜索查詢: '{args.query}'")
+            print("=" * 60)
+            for domain, domain_results in results.items():
+                print(f"\n[域: {domain}]")
+                print(format_text(domain_results))
+    else:
+        # 自動偵測或指定域
+        domain = args.domain
+        if domain is None:
+            domain = detect_domain(args.query)
+            print(f"自動偵測域: {domain}\n", file=sys.stderr)
+
+        results = search(args.query, domain=domain, max_results=args.max)
+
+        if args.format == 'json':
+            print(format_json(results))
+        else:
+            print(f"搜索查詢: '{args.query}' (域: {domain})")
+            print("=" * 60)
+            print(format_text(results))
+
+
+if __name__ == '__main__':
+    main()

package/assets/taiwan-logistics/scripts/test_logistics.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""
+ECPay Logistics API 連線測試腳本
+
+用法:
+    python test_logistics.py              # 測試連線
+    python test_logistics.py --create     # 建立測試訂單
+    python test_logistics.py --query ORDER123  # 查詢訂單
+"""
+
+import hashlib
+import urllib.parse
+import time
+import sys
+import argparse
+from datetime import datetime
+
+try:
+    import requests
+    HAS_REQUESTS = True
+except ImportError:
+    HAS_REQUESTS = False
+
+
+# ECPay 測試環境設定
+TEST_CONFIG = {
+    'merchant_id': '2000132',
+    'hash_key': '5294y06JbISpM5x9',
+    'hash_iv': 'v77hoKGq4kWxNNIS',
+    'create_url': 'https://logistics-stage.ecpay.com.tw/Express/Create',
+    'query_url': 'https://logistics-stage.ecpay.com.tw/Helper/QueryLogisticsTradeInfo/V2',
+}
+
+
+def generate_check_mac_value(params: dict, hash_key: str, hash_iv: str) -> str:
+    """計算 CheckMacValue (MD5)"""
+    sorted_params = sorted(params.items())
+    param_str = '&'.join(f'{k}={v}' for k, v in sorted_params)
+    raw = f'HashKey={hash_key}&{param_str}&HashIV={hash_iv}'
+    encoded = urllib.parse.quote_plus(raw).lower()
+    return hashlib.md5(encoded.encode('utf-8')).hexdigest().upper()
+
+
+def test_connection():
+    """測試 ECPay Logistics API 連線"""
+    print('=' * 60)
+    print('ECPay Logistics API 連線測試')
+    print('=' * 60)
+    print()
+
+    # 測試環境資訊
+    print('[測試環境]')
+    print(f'  商店代號: {TEST_CONFIG["merchant_id"]}')
+    print(f'  HashKey:  {TEST_CONFIG["hash_key"]}')
+    print(f'  HashIV:   {TEST_CONFIG["hash_iv"]}')
+    print()
+
+    # 測試 CheckMacValue 計算
+    print('[CheckMacValue 計算測試]')
+    test_params = {
+        'MerchantID': TEST_CONFIG['merchant_id'],
+        'MerchantTradeNo': 'TEST123456',
+        'LogisticsType': 'CVS',
+    }
+
+    mac = generate_check_mac_value(
+        test_params,
+        TEST_CONFIG['hash_key'],
+        TEST_CONFIG['hash_iv']
+    )
+    print(f'  測試參數: {test_params}')
+    print(f'  CheckMacValue: {mac}')
+    print(f'  長度: {len(mac)} (應為 32, MD5)')
+    print(f'  格式: {"正確" if len(mac) == 32 and mac.isupper() else "錯誤"}')
+    print()
+
+    # 測試網路連線
+    if HAS_REQUESTS:
+        print('[網路連線測試]')
+        try:
+            response = requests.head(
+                'https://logistics-stage.ecpay.com.tw/',
+                timeout=5
+            )
+            print(f'  狀態碼: {response.status_code}')
+            print(f'  連線: {"成功" if response.status_code < 500 else "失敗"}')
+        except requests.RequestException as e:
+            print(f'  連線失敗: {e}')
+    else:
+        print('[網路連線測試]')
+        print('  (需要 requests 套件: pip install requests)')
+    print()
+
+    print('=' * 60)
+    print('測試完成')
+    print('=' * 60)
+
+
+def create_test_order():
+    """建立測試物流訂單"""
+    if not HAS_REQUESTS:
+        print('錯誤: 需要 requests 套件')
+        print('請執行: pip install requests')
+        sys.exit(1)
+
+    order_id = f'TEST{int(time.time())}'
+    trade_date = datetime.now().strftime('%Y/%m/%d %H:%M:%S')
+
+    params = {
+        'MerchantID': TEST_CONFIG['merchant_id'],
+        'MerchantTradeNo': order_id,
+        'MerchantTradeDate': trade_date,
+        'LogisticsType': 'CVS',
+        'LogisticsSubType': 'UNIMART',
+        'GoodsAmount': 500,
+        'GoodsName': '測試商品',
+        'SenderName': '測試寄件人',
+        'SenderPhone': '0912345678',
+        'ReceiverName': '測試收件人',
+        'ReceiverPhone': '0987654321',
+        'ReceiverStoreID': '131386',  # 7-11 測試門市
+        'IsCollection': 'N',
+        'ServerReplyURL': 'https://example.com/callback',
+    }
+
+    params['CheckMacValue'] = generate_check_mac_value(
+        params,
+        TEST_CONFIG['hash_key'],
+        TEST_CONFIG['hash_iv']
+    )
+
+    print('=' * 60)
+    print('建立測試物流訂單')
+    print('=' * 60)
+    print()
+    print(f'訂單編號: {order_id}')
+    print(f'物流類型: 超商取貨 (7-11)')
+    print(f'收件門市: 131386')
+    print()
+
+    try:
+        response = requests.post(
+            TEST_CONFIG['create_url'],
+            data=params,
+            timeout=30
+        )
+
+        print('回應:')
+        result = {}
+        for item in response.text.split('&'):
+            if '=' in item:
+                key, value = item.split('=', 1)
+                result[key] = urllib.parse.unquote(value)
+                print(f'  {key}: {result[key]}')
+
+        if result.get('RtnCode') == '300':
+            print()
+            print('訂單建立成功!')
+        else:
+            print()
+            print(f'訂單建立失敗: {result.get("RtnMsg", "未知錯誤")}')
+
+    except requests.RequestException as e:
+        print(f'請求失敗: {e}')
+
+
+def query_order(order_id: str):
+    """查詢物流訂單狀態"""
+    if not HAS_REQUESTS:
+        print('錯誤: 需要 requests 套件')
+        print('請執行: pip install requests')
+        sys.exit(1)
+
+    params = {
+        'MerchantID': TEST_CONFIG['merchant_id'],
+        'AllPayLogisticsID': '',
+        'MerchantTradeNo': order_id,
+        'TimeStamp': int(time.time()),
+    }
+
+    params['CheckMacValue'] = generate_check_mac_value(
+        params,
+        TEST_CONFIG['hash_key'],
+        TEST_CONFIG['hash_iv']
+    )
+
+    print('=' * 60)
+    print(f'查詢訂單: {order_id}')
+    print('=' * 60)
+    print()
+
+    try:
+        response = requests.post(
+            TEST_CONFIG['query_url'],
+            data=params,
+            timeout=10
+        )
+
+        print('回應:')
+        for item in response.text.split('&'):
+            if '=' in item:
+                key, value = item.split('=', 1)
+                print(f'  {key}: {urllib.parse.unquote(value)}')
+
+    except requests.RequestException as e:
+        print(f'查詢失敗: {e}')
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='ECPay Logistics API 測試工具'
+    )
+    parser.add_argument(
+        '--create',
+        action='store_true',
+        help='建立測試訂單'
+    )
+    parser.add_argument(
+        '--query',
+        type=str,
+        metavar='ORDER_ID',
+        help='查詢訂單狀態'
+    )
+
+    args = parser.parse_args()
+
+    if args.create:
+        create_test_order()
+    elif args.query:
+        query_order(args.query)
+    else:
+        test_connection()
+
+
+if __name__ == '__main__':
+    main()