taiwan-payment-skill 1.0.0

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

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""
+Taiwan Payment BM25 搜索引擎
+
+基於 BM25 (Okapi BM25) 演算法的語義搜索系統
+支援多個搜索域: provider, operation, error, field, payment_method, troubleshoot, reasoning
+
+用法:
+    from core import search, search_all, detect_domain
+
+    # 單域搜索
+    results = search("信用卡", domain="payment_method", max_results=5)
+
+    # 自動偵測域
+    results = search("ECPay 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', 'display_name', 'auth_method', 'features', 'api_style'],
+        'output_cols': ['provider', 'display_name', 'auth_method', 'encryption', 'test_merchant_id', 'features', 'market_share', 'api_style']
+    },
+    'operation': {
+        'file': 'operations.csv',
+        'search_cols': ['operation', 'name_zh', 'name_en', 'description'],
+        'output_cols': ['operation', 'name_zh', 'ecpay_endpoint', 'newebpay_endpoint', 'payuni_endpoint', 'required_fields', 'description']
+    },
+    'error': {
+        'file': 'error-codes.csv',
+        'search_cols': ['provider', 'code', 'message_zh', 'message_en', 'category', 'solution'],
+        'output_cols': ['provider', 'code', 'message_zh', 'category', 'severity', 'solution']
+    },
+    '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']
+    },
+    'payment_method': {
+        'file': 'payment-methods.csv',
+        'search_cols': ['method_id', 'name_zh', 'name_en', 'ecpay_code', 'newebpay_code', 'payuni_code', 'description', 'features'],
+        'output_cols': ['method_id', 'name_zh', 'ecpay_code', 'newebpay_code', 'payuni_code', 'category', 'description', 'features']
+    },
+    'troubleshoot': {
+        'file': 'troubleshooting.csv',
+        'search_cols': ['issue', 'symptom', 'cause', 'solution', 'provider'],
+        'output_cols': ['issue', 'symptom', 'cause', 'solution', 'provider', 'severity']
+    },
+    'reasoning': {
+        'file': 'reasoning.csv',
+        'search_cols': ['scenario', 'recommended_provider', 'reason', 'use_cases', 'anti_patterns'],
+        'output_cols': ['scenario', 'recommended_provider', 'confidence', 'reason', 'anti_patterns', 'use_cases']
+    }
+}
+
+# 域偵測關鍵字
+DOMAIN_KEYWORDS = {
+    'provider': ['ecpay', '綠界', 'newebpay', '藍新', 'payuni', '統一', '金流', '服務商', 'provider'],
+    'operation': ['create', 'query', 'refund', 'void', '建立', '查詢', '退款', '作廢', '請款', 'api', 'endpoint'],
+    'error': ['error', 'code', '錯誤', '失敗', 'failed', '10100', '10200', 'TRA'],
+    'field': ['field', 'parameter', '參數', '欄位', 'merchantid', 'tradeno', 'amount'],
+    'payment_method': ['credit', 'atm', 'cvs', 'barcode', '信用卡', '轉帳', '超商', '支付', '付款方式', 'payment'],
+    'troubleshoot': ['troubleshoot', 'issue', 'problem', '問題', '疑難', '排解', '如何', 'how to'],
+    'reasoning': ['recommend', 'choose', 'select', '推薦', '選擇', '建議', '適合', '比較', 'why', '為什麼']
+}
+
+
+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-payment/scripts/recommend.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""
+Taiwan Payment 推薦系統
+
+基於關鍵字加權評分的智能推薦引擎
+根據需求場景推薦最適合的金流服務商
+
+用法:
+    python recommend.py "高交易量電商"
+    python recommend.py "快速整合 LINE Pay" --format json
+    python recommend.py "新創公司 API" --format simple
+"""
+
+from typing import List, Dict, Tuple, Optional
+import argparse
+import csv
+from pathlib import Path
+from typing import Dict, List, Tuple
+import json
+
+# 路徑設定
+SCRIPT_DIR = Path(__file__).parent
+DATA_DIR = SCRIPT_DIR.parent / 'data'
+
+# 推薦規則 (關鍵字 -> [(provider, 權重, 理由)])
+RECOMMENDATION_RULES = {
+    '穩定': [('ecpay', 3, '市佔率最高，穩定性最佳')],
+    '高交易': [('ecpay', 3, '適合高交易量場景')],
+    '快速': [('ecpay', 2, '文檔完整，整合快速')],
+    '簡單': [('ecpay', 2, '範例豐富，容易上手')],
+    '整合': [('ecpay', 2, '社群資源豐富')],
+    '多元': [('newebpay', 3, '支援最多支付方式')],
+    '支付方式': [('newebpay', 3, '13 種付款方式')],
+    '電子錢包': [('newebpay', 3, 'LINE Pay / Apple Pay / Google Pay')],
+    'line': [('newebpay', 3, '原生支援 LINE Pay')],
+    '行動': [('newebpay', 3, '行動支付完整')],
+    '記憶': [('newebpay', 3, '信用卡記憶功能')],
+    '會員': [('newebpay', 2, '適合會員制電商')],
+    'api': [('payuni', 3, 'RESTful JSON API')],
+    'json': [('payuni', 3, 'JSON 格式友好')],
+    'restful': [('payuni', 3, 'RESTful 設計')],
+    '統一': [('payuni', 2, '統一集團背景')],
+    '新創': [('payuni', 2, 'API 設計優先')],
+    'atm': [('ecpay', 2, 'ATM 虛擬帳號')],
+    '超商': [('ecpay', 2, '四大超商支援')],
+    '定期': [('ecpay', 3, '定期定額扣款')],
+    '訂閱': [('ecpay', 3, '訂閱制服務')],
+    '分期': [('ecpay', 3, '信用卡分期')],
+    'bnpl': [('ecpay', 2, '先買後付')],
+    '測試': [('ecpay', 2, '測試帳號完整')],
+    'php': [('ecpay', 2, 'PHP SDK 完整')],
+    'node': [('payuni', 2, 'JSON API 友好')],
+    'python': [('ecpay', 2, 'Python 範例完整')],
+    'app': [('newebpay', 3, '行動支付完整')],
+    '跨境': [('newebpay', 2, '支援國際卡')],
+    '發票': [('ecpay', 2, '同時支援金流發票')],
+    '物流': [('ecpay', 2, '同時支援金流物流')],
+}
+
+# 反模式 (不建議的場景)
+ANTI_PATTERNS = {
+    'ecpay': [
+        ('無技術資源', 'SHA256 加密流程較複雜，建議有技術人員'),
+        ('極簡需求', '若只需基礎支付，可能功能過多'),
+    ],
+    'newebpay': [
+        ('簡單 API', 'AES 雙層加密較複雜'),
+        ('單一支付', '若只需單一支付方式，不需選擇此平台'),
+    ],
+    'payuni': [
+        ('大型專案', '社群資源較少，大型專案建議選 ECPay'),
+        ('完整文檔', '文檔完整度不如 ECPay'),
+    ]
+}
+
+
+def load_reasoning_csv() -> List[Dict]:
+    """從 reasoning.csv 載入推薦規則"""
+    csv_path = DATA_DIR / 'reasoning.csv'
+    if not csv_path.exists():
+        return []
+
+    rules = []
+    with open(csv_path, 'r', encoding='utf-8') as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            rules.append(row)
+
+    return rules
+
+
+def analyze_requirements(query: str) -> Dict[str, Tuple[int, List[str]]]:
+    """
+    分析需求並計算各服務商的推薦分數
+
+    Returns:
+        {provider: (score, [reasons])}
+    """
+    query_lower = query.lower()
+    scores = {'ecpay': 0, 'newebpay': 0, 'payuni': 0}
+    reasons = {'ecpay': [], 'newebpay': [], 'payuni': []}
+
+    # 基於關鍵字規則計分
+    for keyword, recommendations in RECOMMENDATION_RULES.items():
+        if keyword in query_lower:
+            for provider, weight, reason in recommendations:
+                scores[provider] += weight
+                reasons[provider].append(f'✓ {reason} (+{weight})')
+
+    # 從 CSV 載入額外規則
+    csv_rules = load_reasoning_csv()
+    for rule in csv_rules:
+        scenario = rule.get('scenario', '').lower()
+        if any(word in scenario for word in query_lower.split()):
+            provider = rule.get('recommended_provider', '').lower()
+            if provider in scores:
+                confidence = rule.get('confidence', 'MEDIUM')
+                weight_map = {'HIGH': 3, 'MEDIUM': 2, 'LOW': 1}
+                weight = weight_map.get(confidence, 1)
+                scores[provider] += weight
+
+                reason_text = rule.get('reason', '')
+                if reason_text:
+                    reasons[provider].append(f'✓ {reason_text} (+{weight})')
+
+    return {p: (s, reasons[p]) for p, s in scores.items()}
+
+
+def get_anti_patterns(provider: str) -> List[str]:
+    """獲取反模式警告"""
+    return [f'⚠ {pattern}: {desc}' for pattern, desc in ANTI_PATTERNS.get(provider, [])]
+
+
+def format_recommendation_ascii(results: Dict[str, Tuple[int, List[str]]], query: str) -> str:
+    """格式化輸出 (ASCII Box)"""
+    # 排序
+    sorted_results = sorted(results.items(), key=lambda x: x[1][0], reverse=True)
+
+    output = []
+    output.append('╔' + '═' * 78 + '╗')
+    output.append('║' + f' 台灣金流推薦系統 - 分析結果'.center(76) + '║')
+    output.append('╠' + '═' * 78 + '╣')
+    output.append('║' + f' 查詢: {query}'.ljust(77) + '║')
+    output.append('╚' + '═' * 78 + '╝')
+    output.append('')
+
+    for rank, (provider, (score, reason_list)) in enumerate(sorted_results, 1):
+        if score == 0:
+            continue
+
+        # Provider 名稱
+        provider_names = {
+            'ecpay': '綠界科技 ECPay',
+            'newebpay': '藍新金流 NewebPay',
+            'payuni': '統一金流 PAYUNi'
+        }
+        display_name = provider_names.get(provider, provider)
+
+        # Emoji
+        emoji = '🥇' if rank == 1 else '🥈' if rank == 2 else '🥉'
+
+        output.append(f'{emoji} 推薦 #{rank}: {display_name}')
+        output.append(f'   評分: {score} 分')
+        output.append('')
+
+        if reason_list:
+            output.append('   推薦理由:')
+            for reason in reason_list:
+                output.append(f'      {reason}')
+            output.append('')
+
+        # 反模式警告
+        anti = get_anti_patterns(provider)
+        if anti:
+            output.append('   注意事項:')
+            for warning in anti:
+                output.append(f'      {warning}')
+            output.append('')
+
+        output.append('─' * 80)
+
+    return '\n'.join(output)
+
+
+def format_recommendation_json(results: Dict[str, Tuple[int, List[str]]], query: str) -> str:
+    """格式化輸出 (JSON)"""
+    sorted_results = sorted(results.items(), key=lambda x: x[1][0], reverse=True)
+
+    output_data = {
+        'query': query,
+        'recommendations': []
+    }
+
+    for rank, (provider, (score, reason_list)) in enumerate(sorted_results, 1):
+        if score == 0:
+            continue
+
+        provider_names = {
+            'ecpay': '綠界科技 ECPay',
+            'newebpay': '藍新金流 NewebPay',
+            'payuni': '統一金流 PAYUNi'
+        }
+
+        rec = {
+            'rank': rank,
+            'provider': provider,
+            'display_name': provider_names.get(provider, provider),
+            'score': score,
+            'reasons': [r.replace('✓ ', '').split(' (+')[0] for r in reason_list],
+            'anti_patterns': [a.replace('⚠ ', '') for a in get_anti_patterns(provider)]
+        }
+        output_data['recommendations'].append(rec)
+
+    return json.dumps(output_data, ensure_ascii=False, indent=2)
+
+
+def format_recommendation_simple(results: Dict[str, Tuple[int, List[str]]], query: str) -> str:
+    """格式化輸出 (Simple Text)"""
+    sorted_results = sorted(results.items(), key=lambda x: x[1][0], reverse=True)
+
+    output = [f'查詢: {query}\n']
+
+    for rank, (provider, (score, reason_list)) in enumerate(sorted_results, 1):
+        if score == 0:
+            continue
+
+        provider_names = {
+            'ecpay': '綠界科技 ECPay',
+            'newebpay': '藍新金流 NewebPay',
+            'payuni': '統一金流 PAYUNi'
+        }
+
+        output.append(f'推薦 #{rank}: {provider_names.get(provider, provider)} ({score} 分)')
+
+        if reason_list:
+            for reason in reason_list:
+                output.append(f'  - {reason.replace("✓ ", "")}')
+
+        anti = get_anti_patterns(provider)
+        if anti:
+            for warning in anti:
+                output.append(f'  ! {warning.replace("⚠ ", "")}')
+
+        output.append('')
+
+    return '\n'.join(output)
+
+
+def main():
+    parser = argparse.ArgumentParser(description='台灣金流推薦系統')
+    parser.add_argument('query', type=str, help='需求描述')
+    parser.add_argument('--format', choices=['ascii', 'json', 'simple'], default='ascii', help='輸出格式')
+
+    args = parser.parse_args()
+
+    # 分析需求
+    results = analyze_requirements(args.query)
+
+    # 格式化輸出
+    if args.format == 'json':
+        print(format_recommendation_json(results, args.query))
+    elif args.format == 'simple':
+        print(format_recommendation_simple(results, args.query))
+    else:
+        print(format_recommendation_ascii(results, args.query))
+
+
+if __name__ == '__main__':
+    main()