taiwan-invoice-skill 2.0.0

package/assets/taiwan-invoice/scripts/test-invoice-amounts.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""
+測試與驗證發票金額計算
+
+使用方法:
+    python test-invoice-amounts.py
+"""
+
+
+def calculate_b2c_amounts(total_amount: int):
+    """
+    B2C (二聯式) 金額計算
+    - 金額為含稅價
+    - TaxAmount = 0
+    """
+    return {
+        'type': 'B2C',
+        'salesAmount': total_amount,
+        'taxAmount': 0,
+        'totalAmount': total_amount,
+    }
+
+
+def calculate_b2b_amounts(total_amount: int):
+    """
+    B2B (三聯式) 金額計算
+    - 需分拆未稅金額與稅額
+    - 稅率 5%
+    """
+    tax_amount = round(total_amount - (total_amount / 1.05))
+    sales_amount = total_amount - tax_amount
+
+    return {
+        'type': 'B2B',
+        'salesAmount': sales_amount,
+        'taxAmount': tax_amount,
+        'totalAmount': total_amount,
+    }
+
+
+def verify_calculation(amounts: dict):
+    """驗證計算是否正確"""
+    calculated_total = amounts['salesAmount'] + amounts['taxAmount']
+    is_valid = calculated_total == amounts['totalAmount']
+
+    return is_valid, calculated_total
+
+
+def test_amounts():
+    """測試各種金額"""
+    test_cases = [
+        1050,   # 標準金額
+        100,    # 小金額
+        10000,  # 大金額
+        9999,   # 奇數金額
+        1,      # 最小金額
+    ]
+
+    print("=" * 60)
+    print("台灣電子發票金額計算測試")
+    print("=" * 60)
+
+    for amount in test_cases:
+        print(f"\n測試金額: NT$ {amount:,}")
+        print("-" * 60)
+
+        # B2C 計算
+        b2c = calculate_b2c_amounts(amount)
+        b2c_valid, b2c_total = verify_calculation(b2c)
+
+        print(f"\nB2C (二聯式):")
+        print(f"   銷售額 (含稅): {b2c['salesAmount']:,}")
+        print(f"   稅額:          {b2c['taxAmount']:,}")
+        print(f"   總計:          {b2c['totalAmount']:,}")
+        print(f"   驗證: {'[PASS]' if b2c_valid else '[FAIL]'}")
+
+        # B2B 計算
+        b2b = calculate_b2b_amounts(amount)
+        b2b_valid, b2b_total = verify_calculation(b2b)
+
+        print(f"\nB2B (三聯式):")
+        print(f"   銷售額 (未稅): {b2b['salesAmount']:,}")
+        print(f"   稅額:          {b2b['taxAmount']:,}")
+        print(f"   總計:          {b2b['totalAmount']:,}")
+        print(f"   驗證: {'[PASS]' if b2b_valid else '[FAIL]'}")
+
+        # 反推稅率
+        if b2b['salesAmount'] > 0:
+            tax_rate = (b2b['taxAmount'] / b2b['salesAmount']) * 100
+            print(f"   實際稅率:      {tax_rate:.2f}%")
+
+
+def test_product_items():
+    """測試商品明細計算"""
+    print("\n" + "=" * 60)
+    print("商品明細計算測試")
+    print("=" * 60)
+
+    # 測試案例：購物車有多個商品
+    items = [
+        {'name': '商品A', 'price': 100, 'qty': 2},  # 200
+        {'name': '商品B', 'price': 150, 'qty': 1},  # 150
+        {'name': '商品C', 'price': 500, 'qty': 3},  # 1500
+    ]
+
+    print("\n購物車商品:")
+    total = 0
+    for item in items:
+        amount = item['price'] * item['qty']
+        total += amount
+        print(f"   {item['name']}: NT$ {item['price']:,} x {item['qty']} = NT$ {amount:,}")
+
+    print(f"\n   小計: NT$ {total:,}")
+
+    # B2B 分拆
+    b2b = calculate_b2b_amounts(total)
+    print(f"\nB2B 三聯式發票:")
+    print(f"   未稅金額: NT$ {b2b['salesAmount']:,}")
+    print(f"   稅額 (5%): NT$ {b2b['taxAmount']:,}")
+    print(f"   總計:     NT$ {b2b['totalAmount']:,}")
+
+
+if __name__ == "__main__":
+    test_amounts()
+    test_product_items()
+
+    print("\n" + "=" * 60)
+    print("[DONE] 測試完成")
+    print("=" * 60)

package/assets/templates/base/skill-content.md

@@ -0,0 +1,361 @@
+# {{TITLE}}
+
+> {{DESCRIPTION}}
+
+## Quick Navigation
+
+### Related Documents
+When using this skill, refer to the API reference documents in the project:
+- `references/ECPAY_API_REFERENCE.md` - ECPay API Specification
+- `references/SMILEPAY_API_REFERENCE.md` - SmilePay API Specification
+- `references/AMEGO_API_REFERENCE.md` - Amego API Specification
+- [EXAMPLES.md](EXAMPLES.md) - Code Examples
+
+### When to Use This Skill
+- Developing e-invoice issuance functionality
+- Integrating Taiwan E-Invoice provider APIs
+- Implementing B2C or B2B invoices
+- Handling invoice printing, void, and allowance
+- Processing encryption/signatures (AES, MD5)
+- Troubleshooting invoice API integration issues
+
+## Invoice Types
+
+### B2C Invoice (Two-Part)
+- Buyer without tax ID
+- `BuyerIdentifier` = `0000000000`
+- Amount is **tax-inclusive**
+- Can use carrier or donation
+- Example: General consumer purchase
+
+### B2B Invoice (Three-Part)
+- Buyer has 8-digit tax ID
+- `BuyerIdentifier` = actual tax ID (validate format)
+- Amount is **pre-tax**, requires separate tax calculation
+- **Cannot** use carrier or donation
+- Example: Company purchase
+
+## Provider Comparison
+
+| Feature | ECPay | SmilePay | Amego |
+|---------|-------|----------|-------|
+| Test/Prod URL | Different URLs | Different URLs | **Same URL** |
+| Authentication | AES encryption + HashKey/HashIV | Grvc + Verify_key | MD5 signature + App Key |
+| Print Method | POST form submit | GET URL params | API returns PDF URL |
+| B2B Amount Field | SalesAmount (pre-tax) | UnitTAX=N | DetailVat=0 |
+| Transport Format | JSON (AES encrypted) | URL Parameters | JSON (URL Encoded) |
+
+## Implementation Steps
+
+### 1. Service Architecture
+
+Create services following this structure:
+
+```typescript
+// lib/services/invoice-provider.ts - Interface definition
+export interface InvoiceService {
+    issueInvoice(userId: string, data: InvoiceIssueData): Promise<InvoiceIssueResponse>
+    voidInvoice(userId: string, invoiceNumber: string, reason: string): Promise<InvoiceVoidResponse>
+    printInvoice(userId: string, invoiceNumber: string): Promise<InvoicePrintResponse>
+}
+
+// lib/services/{provider}-invoice-service.ts - Provider implementation
+export class ECPayInvoiceService implements InvoiceService {
+    private async encryptData(data: any, hashKey: string, hashIV: string): Promise<string> {
+        // AES-128-CBC encryption implementation
+    }
+
+    async issueInvoice(userId: string, data: InvoiceIssueData) {
+        // 1. Get user settings
+        // 2. Prepare API data
+        // 3. Encrypt and sign
+        // 4. Send request
+        // 5. Decrypt response
+        // 6. Return standard format
+    }
+}
+```
+
+### 2. Amount Calculation
+
+**Tax-inclusive total -> Pre-tax amount + Tax:**
+
+```typescript
+function calculateInvoiceAmounts(totalAmount: number, isB2B: boolean) {
+    if (isB2B) {
+        // B2B: Need to split tax
+        const taxAmount = Math.round(totalAmount - (totalAmount / 1.05))
+        const salesAmount = totalAmount - taxAmount
+        return { salesAmount, taxAmount, totalAmount }
+    } else {
+        // B2C: Tax-inclusive total
+        return { salesAmount: totalAmount, taxAmount: 0, totalAmount }
+    }
+}
+
+// Example
+const amounts = calculateInvoiceAmounts(1050, true)
+// { salesAmount: 1000, taxAmount: 50, totalAmount: 1050 }
+```
+
+### 3. Encryption Implementation
+
+**ECPay - AES Encryption:**
+
+```typescript
+import crypto from 'crypto'
+
+function encryptECPay(data: object, hashKey: string, hashIV: string): string {
+    // 1. Convert JSON to string and URL encode
+    const jsonString = JSON.stringify(data)
+    const urlEncoded = encodeURIComponent(jsonString)
+
+    // 2. AES-128-CBC encryption
+    const cipher = crypto.createCipheriv('aes-128-cbc', hashKey, hashIV)
+    let encrypted = cipher.update(urlEncoded, 'utf8', 'base64')
+    encrypted += cipher.final('base64')
+
+    return encrypted
+}
+
+function decryptECPay(encryptedData: string, hashKey: string, hashIV: string): object {
+    const decipher = crypto.createDecipheriv('aes-128-cbc', hashKey, hashIV)
+    let decrypted = decipher.update(encryptedData, 'base64', 'utf8')
+    decrypted += decipher.final('utf8')
+
+    const urlDecoded = decodeURIComponent(decrypted)
+    return JSON.parse(urlDecoded)
+}
+```
+
+**Amego - MD5 Signature:**
+
+```typescript
+function generateAmegoSign(data: object, time: number, appKey: string): string {
+    const dataString = JSON.stringify(data)
+    const signString = dataString + time + appKey
+    return crypto.createHash('md5').update(signString).digest('hex')
+}
+```
+
+### 4. Provider Binding
+
+**Key: When issuing invoice, must record the provider used so printing can call the correct one**
+
+```typescript
+// Save provider when issuing
+await prisma.financialRecord.update({
+    where: { id: recordId },
+    data: {
+        invoiceNo: result.invoiceNumber,
+        invoiceProvider: actualProvider,  // 'ECPAY' | 'SMILEPAY' | 'AMEGO'
+        invoiceRandomNum: result.randomNumber, // **Important**: needed for printing
+        invoiceDate: new Date(),
+    }
+})
+
+// Use the issuing provider when printing
+const service = record.invoiceProvider
+    ? InvoiceServiceFactory.getService(record.invoiceProvider)
+    : await InvoiceServiceFactory.getServiceForUser(userId)
+```
+
+### 5. Print Response Handling
+
+Frontend needs to handle based on response type:
+
+```typescript
+// Backend response format
+interface InvoicePrintResponse {
+    success: boolean
+    type?: 'html' | 'redirect' | 'form'
+    htmlContent?: string      // ECPay
+    printUrl?: string          // SmilePay/Amego
+    formUrl?: string
+    formParams?: Record<string, string>
+}
+
+// Frontend handling example
+if (result.type === 'html') {
+    const win = window.open('', '_blank')
+    win.document.write(result.htmlContent)
+} else if (result.type === 'redirect') {
+    window.open(result.url, '_blank')
+} else if (result.type === 'form') {
+    // Dynamically create form submission
+    const form = document.createElement('form')
+    form.method = 'POST'
+    form.action = result.formUrl
+    form.target = '_blank'
+    // ... add parameters
+    form.submit()
+}
+```
+
+## Common Issues
+
+### Issue 1: Invoice issuance failed with unclear error
+
+**Diagnostic steps:**
+1. Check logger output for complete error in `raw` field
+2. Confirm environment variables (test/prod) are correct
+3. Verify required fields are complete
+
+**ECPay common errors:**
+- `10000006`: RelateNumber duplicate -> Order number already used
+- `10000016`: Amount calculation error -> Check B2C/B2B calculation
+- `10000019`: Cannot use carrier with tax ID -> Remove CarrierType
+
+**SmilePay common errors:**
+- `-10066`: AllAmount validation error -> Check if TotalAmount was sent
+- `-10084`: orderid format error -> Limit to 30 characters
+- `-10053`: Carrier number error -> Validate mobile barcode format
+
+**Amego common errors:**
+- `1002`: OrderId already exists -> Use unique order number
+- `1007`: Amount calculation error -> Check DetailVat setting
+- `1012`: B2B invoice cannot use carrier or donation
+
+### Issue 2: Print shows "Invoice not found"
+
+**Solution:**
+Confirm `invoiceProvider` field is saved correctly, use the issuing provider when printing.
+
+```typescript
+// Correct: Use provider from invoice record
+const service = record.invoiceProvider
+    ? InvoiceServiceFactory.getService(record.invoiceProvider)
+    : await InvoiceServiceFactory.getServiceForUser(userId)
+
+// Incorrect: Use user's current default provider
+const service = await InvoiceServiceFactory.getServiceForUser(userId)
+```
+
+### Issue 3: B2B invoice amount error
+
+**Amount fields by provider:**
+
+```typescript
+// ECPay
+const b2bData = {
+    SalesAmount: 1000,      // Pre-tax sales
+    TaxAmount: 50,          // Tax
+    TotalAmount: 1050,      // Total
+    ItemPrice: 100,         // Item unit price (pre-tax)
+    ItemAmount: 1000,       // Item subtotal (pre-tax)
+    ItemTax: 50             // Item tax
+}
+
+// SmilePay
+const b2bData = {
+    AllAmount: '1050',      // Tax-inclusive total
+    SalesAmount: '1000',    // Pre-tax sales (optional but recommended)
+    TaxAmount: '50',        // Tax (optional)
+    UnitTAX: 'N',           // **Important**: Unit price is pre-tax
+    UnitPrice: '100',       // Item unit price (pre-tax)
+    Amount: '1000'          // Item subtotal (pre-tax)
+}
+
+// Amego
+const b2bData = {
+    DetailVat: 0,           // **Important**: 0=pre-tax
+    SalesAmount: 1000,      // Pre-tax sales
+    TaxAmount: 50,          // Tax
+    TotalAmount: 1050,      // Total
+    ProductItem: [{
+        UnitPrice: 100,     // Item unit price (pre-tax)
+        Amount: 1000        // Item subtotal (pre-tax)
+    }]
+}
+```
+
+### Issue 4: SmilePay print blank
+
+**Cause:** Using `type: 'form'` when response has `method: 'GET'`
+
+**Solution:**
+```typescript
+// Correct
+if (printData.method === 'GET' && printData.url) {
+    return { type: 'redirect', url: printData.url }
+}
+
+// Incorrect
+return { type: 'form', url: printData.url, params: printData.params }
+```
+
+### Issue 5: Timestamp expired
+
+**ECPay error 10000005:** Timestamp exceeds 10 minutes
+
+**Solution:**
+```typescript
+// Ensure using current timestamp
+const timestamp = Math.floor(Date.now() / 1000)
+
+// Amego: tolerance is +/- 60 seconds
+const time = Math.floor(Date.now() / 1000)
+```
+
+## Test Accounts
+
+### ECPay Test Environment
+```
+MerchantID: 2000132
+HashKey: ejCk326UnaZWKisg
+HashIV: q9jcZX8Ib9LM8wYk
+URL: https://einvoice-stage.ecpay.com.tw
+```
+
+### SmilePay Test Environment
+```
+Grvc: SEI1000034
+Verify_key: 9D73935693EE0237FABA6AB744E48661
+Test Tax ID: 80129529
+URL: https://ssl.smse.com.tw/api_test/SPEinvoice_Storage.asp
+```
+
+### Amego Test Environment
+```
+Tax ID: 12345678
+App Key: sHeq7t8G1wiQvhAuIM27
+Admin: https://invoice.amego.tw/
+Test Account: test@amego.tw
+Test Password: 12345678
+```
+
+## Development Checklist
+
+Use this checklist to ensure complete implementation:
+
+- [ ] Implement `InvoiceService` interface
+- [ ] Handle B2C / B2B amount calculation differences
+- [ ] Implement encryption/signature mechanism (AES or MD5)
+- [ ] Save `invoiceProvider` field
+- [ ] Save `invoiceRandomNum` (needed for printing)
+- [ ] Handle print response types (html/redirect/form)
+- [ ] Implement error handling and logging
+- [ ] Test environment verification
+- [ ] Handle carrier and donation mutual exclusion
+- [ ] Validate tax ID format (8-digit number)
+
+## Adding New Provider
+
+1. Create `{provider}-invoice-service.ts` in `lib/services/`
+2. Implement all methods of `InvoiceService` interface
+3. Register new provider in `InvoiceServiceFactory`
+4. Add option to `InvoiceProvider` enum in `prisma/schema.prisma`
+5. Run `prisma migrate` or `prisma db push`
+6. Update frontend settings page (`app/settings/invoice/page.tsx`)
+7. Write unit tests
+
+## References
+
+For detailed API specifications, see the `references/` directory:
+- [ECPay API Specification](./references/ECPAY_API_REFERENCE.md)
+- [SmilePay API Specification](./references/SMILEPAY_API_REFERENCE.md)
+- [Amego API Specification](./references/AMEGO_API_REFERENCE.md)
+
+---
+
+Last updated: 2026/01/28

package/assets/templates/platforms/antigravity.json

@@ -0,0 +1,21 @@
+{
+  "platform": "antigravity",
+  "displayName": "Google Antigravity",
+  "installType": "full",
+  "folderStructure": {
+    "root": ".agent",
+    "skillPath": "skills/taiwan-invoice",
+    "filename": "SKILL.md"
+  },
+  "frontmatter": {
+    "name": "taiwan-invoice",
+    "description": "Taiwan E-Invoice API integration specialist for ECPay, SmilePay, and Amego. Provides B2C/B2B invoice issuance, void, allowance, query, and print functionality."
+  },
+  "sections": {
+    "examples": true,
+    "references": true,
+    "scripts": true
+  },
+  "title": "Taiwan E-Invoice Skill",
+  "description": "Comprehensive guide for Taiwan E-Invoice API integration. Supports ECPay, SmilePay, and Amego providers with B2C/B2B invoice operations."
+}

package/assets/templates/platforms/claude.json

@@ -0,0 +1,22 @@
+{
+  "platform": "claude",
+  "displayName": "Claude Code",
+  "installType": "full",
+  "folderStructure": {
+    "root": ".claude",
+    "skillPath": "skills/taiwan-invoice",
+    "filename": "SKILL.md"
+  },
+  "frontmatter": {
+    "name": "taiwan-invoice",
+    "description": "Taiwan E-Invoice API integration specialist for ECPay, SmilePay, and Amego. Provides B2C/B2B invoice issuance, void, allowance, query, and print functionality. Includes encryption implementations (AES-128-CBC, MD5), tax calculations, and complete API specifications.",
+    "user-invocable": "true"
+  },
+  "sections": {
+    "examples": true,
+    "references": true,
+    "scripts": true
+  },
+  "title": "Taiwan E-Invoice Skill",
+  "description": "Comprehensive guide for Taiwan E-Invoice API integration. Supports ECPay, SmilePay, and Amego providers with B2C/B2B invoice operations."
+}

package/assets/templates/platforms/codebuddy.json

@@ -0,0 +1,18 @@
+{
+  "platform": "codebuddy",
+  "displayName": "CodeBuddy",
+  "installType": "full",
+  "folderStructure": {
+    "root": ".codebuddy",
+    "skillPath": "skills/taiwan-invoice",
+    "filename": "SKILL.md"
+  },
+  "frontmatter": null,
+  "sections": {
+    "examples": true,
+    "references": true,
+    "scripts": true
+  },
+  "title": "Taiwan E-Invoice Skill",
+  "description": "Comprehensive guide for Taiwan E-Invoice API integration. Supports ECPay, SmilePay, and Amego providers with B2C/B2B invoice operations."
+}

package/assets/templates/platforms/codex.json

@@ -0,0 +1,21 @@
+{
+  "platform": "codex",
+  "displayName": "Codex CLI",
+  "installType": "full",
+  "folderStructure": {
+    "root": ".codex",
+    "skillPath": "skills/taiwan-invoice",
+    "filename": "SKILL.md"
+  },
+  "frontmatter": {
+    "name": "taiwan-invoice",
+    "description": "Taiwan E-Invoice API integration specialist for ECPay, SmilePay, and Amego."
+  },
+  "sections": {
+    "examples": true,
+    "references": true,
+    "scripts": true
+  },
+  "title": "Taiwan E-Invoice Skill",
+  "description": "Comprehensive guide for Taiwan E-Invoice API integration. Supports ECPay, SmilePay, and Amego providers with B2C/B2B invoice operations."
+}

package/assets/templates/platforms/continue.json

@@ -0,0 +1,21 @@
+{
+  "platform": "continue",
+  "displayName": "Continue",
+  "installType": "full",
+  "folderStructure": {
+    "root": ".continue",
+    "skillPath": "skills/taiwan-invoice",
+    "filename": "SKILL.md"
+  },
+  "frontmatter": {
+    "name": "taiwan-invoice",
+    "description": "Taiwan E-Invoice API integration specialist for ECPay, SmilePay, and Amego."
+  },
+  "sections": {
+    "examples": true,
+    "references": true,
+    "scripts": true
+  },
+  "title": "Taiwan E-Invoice Skill",
+  "description": "Comprehensive guide for Taiwan E-Invoice API integration. Supports ECPay, SmilePay, and Amego providers with B2C/B2B invoice operations."
+}

package/assets/templates/platforms/copilot.json

@@ -0,0 +1,18 @@
+{
+  "platform": "copilot",
+  "displayName": "GitHub Copilot",
+  "installType": "full",
+  "folderStructure": {
+    "root": ".github",
+    "skillPath": "prompts/taiwan-invoice",
+    "filename": "SKILL.md"
+  },
+  "frontmatter": null,
+  "sections": {
+    "examples": true,
+    "references": true,
+    "scripts": true
+  },
+  "title": "Taiwan E-Invoice Skill",
+  "description": "Comprehensive guide for Taiwan E-Invoice API integration. Supports ECPay, SmilePay, and Amego providers with B2C/B2B invoice operations."
+}

package/assets/templates/platforms/cursor.json

@@ -0,0 +1,21 @@
+{
+  "platform": "cursor",
+  "displayName": "Cursor",
+  "installType": "full",
+  "folderStructure": {
+    "root": ".cursor",
+    "skillPath": "skills/taiwan-invoice",
+    "filename": "SKILL.md"
+  },
+  "frontmatter": {
+    "name": "taiwan-invoice",
+    "description": "Taiwan E-Invoice API integration specialist for ECPay, SmilePay, and Amego. Provides B2C/B2B invoice issuance, void, allowance, query, and print functionality. Includes encryption implementations (AES-128-CBC, MD5), tax calculations, and complete API specifications."
+  },
+  "sections": {
+    "examples": true,
+    "references": true,
+    "scripts": true
+  },
+  "title": "Taiwan E-Invoice Skill",
+  "description": "Comprehensive guide for Taiwan E-Invoice API integration. Supports ECPay, SmilePay, and Amego providers with B2C/B2B invoice operations."
+}

package/assets/templates/platforms/gemini.json

@@ -0,0 +1,21 @@
+{
+  "platform": "gemini",
+  "displayName": "Gemini CLI",
+  "installType": "full",
+  "folderStructure": {
+    "root": ".gemini",
+    "skillPath": "skills/taiwan-invoice",
+    "filename": "SKILL.md"
+  },
+  "frontmatter": {
+    "name": "taiwan-invoice",
+    "description": "Taiwan E-Invoice API integration specialist for ECPay, SmilePay, and Amego."
+  },
+  "sections": {
+    "examples": true,
+    "references": true,
+    "scripts": true
+  },
+  "title": "Taiwan E-Invoice Skill",
+  "description": "Comprehensive guide for Taiwan E-Invoice API integration. Supports ECPay, SmilePay, and Amego providers with B2C/B2B invoice operations."
+}

package/assets/templates/platforms/kiro.json

@@ -0,0 +1,18 @@
+{
+  "platform": "kiro",
+  "displayName": "Kiro",
+  "installType": "full",
+  "folderStructure": {
+    "root": ".kiro",
+    "skillPath": "steering/taiwan-invoice",
+    "filename": "SKILL.md"
+  },
+  "frontmatter": null,
+  "sections": {
+    "examples": true,
+    "references": true,
+    "scripts": true
+  },
+  "title": "Taiwan E-Invoice Skill",
+  "description": "Comprehensive guide for Taiwan E-Invoice API integration. Supports ECPay, SmilePay, and Amego providers with B2C/B2B invoice operations."
+}