taiwan-ecommerce-toolkit: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Taiwan Invoice Skill is an AI-powered toolkit for Taiwan E-Invoice integration, providing API documentation, code examples, and scripts for Taiwan invoice platforms (ECPay, SmilePay, Amego, ezPay, PayNow, O'Pay, SunPay; MOF platform for queries). It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).

Available Scripts

# 搜尋（provider / operation / error / field / tax / troubleshoot / reasoning）
python3 taiwan-invoice/scripts/search.py "<query>" --domain error

# 推薦加值中心
python3 taiwan-invoice/scripts/recommend.py "<需求>"

# 產生服務骨架（未實作的步驟會拋 NotImplementedError）
python3 taiwan-invoice/scripts/generate-invoice-service.py <Provider> --lang python|typescript --output <dir>

# 驗證（repo 根目錄）
python3 scripts/validate-data.py
python3 scripts/verify-examples.py

Supported Platforms: ecpay, smilepay, amego, ezpay, paynow, opay, mof（財政部大平台）

Note: mof 是財政部電子發票整合服務平台（上游），只做查詢/驗證，不能開立發票。見 taiwan-invoice/references/MOF_EINVOICE_API_REFERENCE.md。

Architecture

taiwan-invoice/                     # Source of Truth
├── SKILL.md                        # Main skill documentation
├── EXAMPLES.md                     # Code examples and patterns
├── references/                     # API documentation（各服務商 *_API_REFERENCE.md）
├── examples/                       # 可執行範例（CI 以官方測試向量驗證）
├── data/                           # search / recommend 使用的 CSV
└── scripts/                        # search.py、recommend.py、generate-invoice-service.py、persist.py、error_handler.py

invoice-cli/                        # CLI installer (taiwan-invoice-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-invoice/             # Copy of taiwan-invoice/
    └── templates/
        ├── base/                   # Base templates (skill-content.md)
        └── platforms/              # Platform configs (14 platforms)

.claude/skills/taiwan-invoice/      # Claude Code skill (generated by CLI)