taiwan-payment-skill 1.0.0

package/README.md

@@ -0,0 +1,197 @@
+<h1 align="center">taiwan-payment-skill</h1>
+
+<h3 align="center">台灣金流 AI 開發技能包</h3>
+
+<p align="center">
+  <strong>支援 ECPay 綠界 · NewebPay 藍新 · PAYUNi 統一</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/taiwan-payment-skill"><img src="https://img.shields.io/npm/v/taiwan-payment-skill?style=flat-square&logo=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/taiwan-payment-skill"><img src="https://img.shields.io/npm/dm/taiwan-payment-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D18-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js">
+  <img src="https://img.shields.io/badge/platforms-14-blue?style=flat-square" alt="14 Platforms">
+  <a href="https://github.com/Moksa1123/taiwan-payment/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Moksa1123/taiwan-payment?style=flat-square" alt="License"></a>
+</p>
+
+<p align="center">
+  <a href="https://paypal.me/cccsubcom"><img src="https://img.shields.io/badge/PayPal-支持開發-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="PayPal"></a>
+</p>
+
+---
+
+## 安裝
+
+```bash
+npm install -g taiwan-payment-skill
+```
+
+---
+
+## 使用方式
+
+```bash
+# 進入專案目錄
+cd /path/to/your/project
+
+# 選擇你的 AI 助手
+taiwan-payment init --ai claude        # Claude Code
+taiwan-payment init --ai cursor        # Cursor
+taiwan-payment init --ai windsurf      # Windsurf
+taiwan-payment init --ai copilot       # GitHub Copilot
+taiwan-payment init --ai antigravity   # Antigravity
+taiwan-payment init --ai all           # 全部安裝
+```
+
+<details>
+<summary>完整平台列表</summary>
+
+```bash
+taiwan-payment init --ai kiro          # Kiro (AWS)
+taiwan-payment init --ai codex         # Codex CLI (OpenAI)
+taiwan-payment init --ai qoder         # Qoder
+taiwan-payment init --ai roocode       # Roo Code
+taiwan-payment init --ai gemini        # Gemini CLI
+taiwan-payment init --ai trae          # Trae (ByteDance)
+taiwan-payment init --ai opencode      # OpenCode
+taiwan-payment init --ai continue      # Continue
+taiwan-payment init --ai codebuddy     # CodeBuddy (Tencent)
+```
+
+</details>
+
+---
+
+## 其他指令
+
+```bash
+taiwan-payment list         # 列出支援平台
+taiwan-payment info         # 顯示技能資訊
+taiwan-payment versions     # 列出可用版本
+taiwan-payment update       # 檢查更新
+```
+
+### 選項
+
+```bash
+taiwan-payment init --force     # 覆蓋現有檔案
+taiwan-payment init --global    # 安裝到全域目錄（所有專案共用）
+```
+
+### 全域安裝
+
+使用 `--global` 可將技能安裝到使用者目錄，讓所有專案都能使用：
+
+```bash
+taiwan-payment init --ai cursor --global       # ~/.cursor/skills/taiwan-payment/
+taiwan-payment init --ai claude --global       # ~/.claude/skills/taiwan-payment/
+taiwan-payment init --ai antigravity --global  # ~/.gemini/antigravity/global_skills/taiwan-payment/
+```
+
+---
+
+## 支援平台
+
+| 平台 | 說明 | 啟動方式 |
+|------|------|----------|
+| **Claude Code** | Anthropic 官方 CLI | `/taiwan-payment` |
+| **Cursor** | AI 程式編輯器 | `/taiwan-payment` |
+| **Windsurf** | Codeium 編輯器 | 自動 |
+| **Copilot** | GitHub Copilot | `/taiwan-payment` |
+| **Antigravity** | Google AI 助手 | `/taiwan-payment` |
+| **Kiro** | AWS AI 助手 | `/taiwan-payment` |
+| **Codex** | OpenAI CLI | 自動 |
+| **Qoder** | Qodo AI 助手 | 自動 |
+| **RooCode** | VSCode 擴充 | `/taiwan-payment` |
+| **Gemini CLI** | Google Gemini | 自動 |
+| **Trae** | ByteDance AI | 自動 |
+| **OpenCode** | 開源 AI 助手 | 自動 |
+| **Continue** | 開源 AI 助手 | 自動 |
+| **CodeBuddy** | Tencent AI | 自動 |
+
+---
+
+## 金流服務商
+
+| 服務商 | 加密方式 | API 風格 | 特點 |
+|--------|---------|---------|------|
+| **ECPay 綠界** | URL Encode + SHA256 | Form POST | 市佔率最高，穩定性佳 |
+| **NewebPay 藍新** | AES-256-CBC + SHA256 | Form POST + AES | 支援最多支付方式 (13 種) |
+| **PAYUNi 統一** | AES-256-GCM + SHA256 | RESTful JSON | RESTful 設計，API 現代化 |
+
+---
+
+## 付款方式支援
+
+### 信用卡支付
+- 一次付清、分期付款 (3/6/12/18/24 期)
+- 信用卡定期定額、信用卡記憶
+
+### 電子錢包
+- Apple Pay、Google Pay、Samsung Pay
+- LINE Pay、台灣 Pay
+
+### 轉帳支付
+- 網路 ATM、ATM 虛擬帳號
+
+### 超商支付
+- 超商代碼、超商條碼
+
+### 其他
+- TWQR、BNPL 無卡分期、AFTEE 先享後付
+
+---
+
+## 智能工具
+
+安裝後包含以下 Python 工具（純 Python，無需外部依賴）：
+
+```bash
+# BM25 搜索引擎 - 搜索錯誤碼、欄位映射、付款方式
+python scripts/search.py "10100058" --domain error
+python scripts/search.py "信用卡" --domain payment_method
+python scripts/search.py "CheckMacValue" --domain troubleshoot
+
+# 智能推薦系統 - 根據需求推薦金流服務商
+python scripts/recommend.py "高交易量 電商 穩定"
+python scripts/recommend.py "多元支付 LINE Pay Apple Pay"
+
+# 連線測試工具 - 測試 API 連線
+python scripts/test_payment.py ecpay
+python scripts/test_payment.py all
+```
+
+### 搜索域
+
+- `provider` - 服務商比較
+- `operation` - API 操作端點
+- `error` - 錯誤碼查詢
+- `field` - 欄位映射
+- `payment_method` - 付款方式
+- `troubleshoot` - 疑難排解
+- `reasoning` - 推薦決策規則
+
+---
+
+## 功能特色
+
+- 完整 API 文檔 (ECPay, NewebPay, PAYUNi)
+- BM25 搜索引擎 (311 行)
+- 智能推薦系統 (373 行)
+- 9 組完整代碼範例 (TypeScript/Python)
+- 7 個 CSV 數據檔 (易於維護)
+- 加密實作指南 (SHA256, AES-CBC, AES-GCM)
+- 16 個疑難排解案例
+
+---
+
+## 授權
+
+[MIT License](https://github.com/Moksa1123/taiwan-payment/blob/main/LICENSE)
+
+---
+
+<p align="center">
+  <sub>Made by <strong>Moksa</strong></sub><br>
+  <sub>service@moksaweb.com</sub>
+</p>

package/assets/taiwan-payment/CLAUDE.md

@@ -0,0 +1,297 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Taiwan Payment Skill is an AI-powered toolkit for Taiwan Payment Gateway integration, providing API documentation, code examples, and scripts for major payment platforms (ECPay, NewebPay, PAYUNi). It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
+
+## Available Scripts
+
+```bash
+# Search API documentation
+python3 taiwan-payment/scripts/search.py "<query>" [--domain <domain>]
+
+# Recommend payment provider
+python3 taiwan-payment/scripts/recommend.py "<requirements>"
+
+# Test API connectivity
+python3 taiwan-payment/scripts/test_payment.py [--platform <platform>]
+```
+
+**Supported Platforms:** `ecpay`, `newebpay`, `payuni`
+
+**Search Domains:** `provider`, `operation`, `error`, `field`, `payment_method`, `troubleshoot`, `reasoning`
+
+## Architecture
+
+```
+taiwan-payment/                     # Source of Truth
+├── SKILL.md                        # Main skill documentation (857 lines)
+├── EXAMPLES.md                     # Code examples and patterns (1425 lines)
+├── references/                     # API documentation
+│   ├── ecpay-payment-api.md
+│   ├── newebpay-payment-api.md
+│   └── payuni-payment-api.md
+├── scripts/                        # Utility scripts
+│   ├── core.py                     # BM25 search engine (311 lines)
+│   ├── recommend.py                # Recommendation system (373 lines)
+│   ├── search.py                   # Search CLI (150+ lines)
+│   └── test_payment.py             # Connection testing (359 lines)
+└── data/                           # Data-driven architecture (7 CSVs)
+    ├── providers.csv               # 3 providers with details
+    ├── operations.csv              # 8 API operations
+    ├── error-codes.csv             # 20+ error codes + solutions
+    ├── field-mappings.csv          # 15 field mappings
+    ├── payment-methods.csv         # 24 payment methods
+    ├── reasoning.csv               # 30+ recommendation rules
+    └── troubleshooting.csv         # 16 troubleshooting cases
+
+cli/                                # CLI installer (taiwan-payment-skill on npm)
+├── src/
+│   ├── commands/init.ts            # Install command with template generation
+│   ├── utils/template.ts           # Template rendering engine
+│   ├── utils/detect.ts             # AI type detection
+│   └── utils/logger.ts             # Logging utilities
+└── assets/                         # Bundled assets
+    ├── taiwan-payment/             # Copy of taiwan-payment/
+    └── templates/
+        ├── base/                   # Base templates (skill-content.md, quick-reference.md)
+        └── platforms/              # Platform configs (14 platforms)
+
+.claude/skills/taiwan-payment/      # Claude Code skill (generated by CLI)
+```
+
+## Sync Rules
+
+**Source of Truth:** `taiwan-payment/`
+
+When modifying files:
+
+1. **Skill Content** - Edit in `taiwan-payment/`:
+   - `SKILL.md` - Main documentation
+   - `EXAMPLES.md` - Code examples
+   - `references/*.md` - API documentation
+   - `scripts/*.py` - Utility scripts
+   - `data/*.csv` - Data files
+
+2. **Templates** - Edit in `cli/assets/templates/`:
+   - `base/skill-content.md` - Common skill content
+   - `base/quick-reference.md` - Quick reference (Claude only)
+   - `platforms/*.json` - Platform-specific configs (14 platforms)
+
+3. **CLI Assets** - Run sync before publishing:
+   ```bash
+   cp -r taiwan-payment/* cli/assets/taiwan-payment/
+   ```
+
+4. **Reference Folders** - No manual sync needed. The CLI generates these from templates during `taiwan-payment init`.
+
+## Supported AI Platforms
+
+| Platform     | Folder      | Install Type |
+|-------------|-------------|--------------|
+| Claude Code | `.claude`   | full         |
+| Cursor      | `.cursor`   | full         |
+| Windsurf    | `.windsurf` | full         |
+| Antigravity | `.agent`    | full         |
+| Copilot     | `.github`   | full         |
+| Kiro        | `.kiro`     | full         |
+| Codex       | `.codex`    | full         |
+| Qoder       | `.qoder`    | full         |
+| Roo Code    | `.roo`      | full         |
+| Gemini      | `.gemini`   | full         |
+| Trae        | `.trae`     | full         |
+| OpenCode    | `.opencode` | full         |
+| Continue    | `.continue` | full         |
+| CodeBuddy   | `.codebuddy`| full         |
+
+## Prerequisites
+
+- Node.js 18+ (for CLI)
+- Python 3.x (for scripts, no external dependencies)
+
+## Git Workflow
+
+Never push directly to `main`. Always:
+
+1. Create a new branch: `git checkout -b feat/...` or `fix/...`
+2. Commit changes
+3. Push branch: `git push -u origin <branch>`
+4. Create PR: `gh pr create`
+
+## Development Guidelines
+
+### When Working with Payment Integration
+
+1. **Always verify CheckMacValue/CheckSum** - This is the most critical security measure
+2. **Use test accounts** - Never use production credentials in examples
+3. **Handle errors gracefully** - Payment failures are common, always provide fallback
+4. **HTTPS only** - All callback URLs must use HTTPS
+5. **Amount validation** - Always validate amounts are positive integers
+6. **Idempotency** - Ensure order IDs are unique to prevent duplicate payments
+
+### Common Pitfalls
+
+1. **CheckMacValue calculation errors**:
+   - Must sort parameters alphabetically
+   - Must use lowercase URL encoding
+   - Must exclude CheckMacValue itself from calculation
+
+2. **AES encryption errors**:
+   - NewebPay: Ensure Key=32 bytes, IV=16 bytes, use PKCS7 padding
+   - PAYUNi: Must append 16-byte auth tag after encryption
+
+3. **Payment notification handling**:
+   - Always verify CheckMacValue before processing
+   - Return "1|OK" for ECPay, handle appropriately for others
+   - Use database transactions to prevent duplicate processing
+
+### Code Review Checklist
+
+- [ ] Sensitive data (HashKey/HashIV) not exposed in frontend
+- [ ] CheckMacValue/CheckSum properly calculated and verified
+- [ ] HTTPS used for all callback URLs
+- [ ] Proper error handling for payment failures
+- [ ] Unique order IDs generated
+- [ ] Test accounts used in examples
+- [ ] Comments explain complex encryption logic
+- [ ] CSV data validated and consistent
+
+## Smart Tools Usage
+
+### BM25 Search
+
+Use when user asks about:
+- "What's error code 10100058?"
+- "How to map MerchantID field?"
+- "Which payment methods does ECPay support?"
+
+```bash
+python3 scripts/search.py "<query>" [--domain <domain>] [--format json]
+```
+
+### Recommendation System
+
+Use when user asks:
+- "Which payment provider should I use?"
+- "Best for high-volume e-commerce?"
+- "Need LINE Pay integration"
+
+```bash
+python3 scripts/recommend.py "<requirements>" [--format ascii|json|simple]
+```
+
+### Connection Testing
+
+Use when user wants to:
+- Test API connectivity
+- Verify encryption implementation
+- Check test credentials
+
+```bash
+python3 scripts/test_payment.py [--platform ecpay|newebpay|payuni]
+```
+
+## Data-Driven Architecture
+
+All core logic is in CSV files:
+
+- **providers.csv** - Provider details (encryption, API endpoints, test accounts)
+- **operations.csv** - API operations (create, query, refund, etc.)
+- **error-codes.csv** - Error code lookup table
+- **field-mappings.csv** - Field name mappings across providers
+- **payment-methods.csv** - Payment method details
+- **reasoning.csv** - Recommendation rules (30+ scenarios)
+- **troubleshooting.csv** - Common issues and solutions
+
+To add new data, edit CSV files directly. No code changes needed.
+
+## Encryption Methods
+
+### ECPay - SHA256
+
+```python
+def generate_check_mac_value(params, hash_key, hash_iv):
+    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.sha256(encoded.encode('utf-8')).hexdigest().upper()
+```
+
+### NewebPay - AES-256-CBC + SHA256
+
+```python
+def generate_trade_info(params, hash_key, hash_iv):
+    query_string = urllib.parse.urlencode(params)
+    cipher = AES.new(hash_key.encode(), AES.MODE_CBC, hash_iv.encode())
+    padded = pad(query_string.encode(), AES.block_size)
+    return cipher.encrypt(padded).hex()
+
+def generate_trade_sha(trade_info, hash_key, hash_iv):
+    raw = f'HashKey={hash_key}&{trade_info}&HashIV={hash_iv}'
+    return hashlib.sha256(raw.encode()).hexdigest().upper()
+```
+
+### PAYUNi - AES-256-GCM + SHA256
+
+```python
+def generate_encrypt_info(params, hash_key, hash_iv):
+    query_string = urllib.parse.urlencode(params)
+    cipher = AES.new(hash_key.encode(), AES.MODE_GCM, nonce=hash_iv.encode())
+    encrypted, tag = cipher.encrypt_and_digest(query_string.encode())
+    return (encrypted + tag).hex()  # Must append tag!
+
+def generate_hash_info(encrypt_info, hash_key, hash_iv):
+    raw = encrypt_info + hash_key + hash_iv
+    return hashlib.sha256(raw.encode()).hexdigest().upper()
+```
+
+## Test Accounts
+
+### ECPay
+```
+商店代號: 3002607
+HashKey:  pwFHCqoQZGmho4w6
+HashIV:   EkRm7iFT261dpevs
+測試網址: https://payment-stage.ecpay.com.tw/Cashier/AioCheckOut/V5
+測試卡號: 4311-9522-2222-2222
+```
+
+### NewebPay
+```
+商店代號: 請至後台申請
+HashKey:  請至後台申請
+HashIV:   請至後台申請
+測試網址: https://ccore.newebpay.com/MPG/mpg_gateway
+測試卡號: 4000-2211-1111-1111
+```
+
+### PAYUNi
+```
+商店代號: 請至後台申請
+HashKey:  請至後台申請
+HashIV:   請至後台申請
+測試網址: https://sandbox-api.payuni.com.tw/api/upp
+測試卡號: 4000-2211-1111-1111
+```
+
+## Publishing Workflow
+
+Before publishing to npm:
+
+1. Update version in `cli/package.json`
+2. Sync assets: `cp -r taiwan-payment/* cli/assets/taiwan-payment/`
+3. Build CLI: `cd cli && npm run build`
+4. Test locally: `npm test`
+5. Publish: `npm publish`
+
+## Related Projects
+
+- **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego)
+- **Taiwan Logistics Skill** - Logistics integration (ECPay, NewebPay, PAYUNi)
+
+---
+
+**Last Updated**: 2026-01-29