taiwan-payment-skill 1.0.2 → 1.0.4

package/README.md

@@ -176,8 +176,8 @@ python scripts/test_payment.py all
 ## 功能特色
 
 - 完整 API 文檔 (ECPay, NewebPay, PAYUNi)
-- BM25 搜索引擎 (311 行)
-- 智能推薦系統 (373 行)
+- BM25 搜索引擎
+- 智能推薦系統
 - 9 組完整代碼範例 (TypeScript/Python)
 - 7 個 CSV 數據檔 (易於維護)
 - 加密實作指南 (SHA256, AES-CBC, AES-GCM)

package/assets/taiwan-payment/CLAUDE.md

@@ -1,297 +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
+# 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
+├── EXAMPLES.md                     # Code examples and patterns
+├── references/                     # API documentation
+│   ├── ecpay-payment-api.md
+│   ├── newebpay-payment-api.md
+│   └── payuni-payment-api.md
+├── scripts/                        # Utility scripts
+│   ├── core.py                     # BM25 search engine
+│   ├── recommend.py                # Recommendation system
+│   ├── search.py                   # Search CLI (150+ lines)
+│   └── test_payment.py             # Connection testing
+└── 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