taiwan-logistics-skill 1.2.2 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +132 -132
  2. package/assets/taiwan-logistics/CLAUDE.md +147 -137
  3. package/assets/taiwan-logistics/EXAMPLES.md +3258 -3258
  4. package/assets/taiwan-logistics/README.md +132 -132
  5. package/assets/taiwan-logistics/SKILL.md +845 -845
  6. package/assets/taiwan-logistics/data/field-mappings.csv +23 -27
  7. package/assets/taiwan-logistics/data/logistics-types.csv +29 -25
  8. package/assets/taiwan-logistics/data/operations.csv +32 -32
  9. package/assets/taiwan-logistics/data/providers.csv +20 -15
  10. package/assets/taiwan-logistics/data/status-codes.csv +89 -35
  11. package/assets/taiwan-logistics/examples/ecpay-logistics-cvs-example.py +175 -175
  12. package/assets/taiwan-logistics/examples/newebpay-logistics-cvs-example.py +524 -524
  13. package/assets/taiwan-logistics/examples/payuni-logistics-cvs-example.py +605 -605
  14. package/assets/taiwan-logistics/examples/store-map-integration-example.html +573 -573
  15. package/assets/taiwan-logistics/references/NEWEBPAY_LOGISTICS_REFERENCE.md +774 -774
  16. package/assets/taiwan-logistics/references/carrier-direct-access.md +134 -0
  17. package/assets/taiwan-logistics/references/ecpay-logistics-api.md +536 -536
  18. package/assets/taiwan-logistics/references/ezship-logistics-api.md +103 -0
  19. package/assets/taiwan-logistics/references/hct-logistics-api.md +1102 -1102
  20. package/assets/taiwan-logistics/references/lalamove-logistics-api.md +138 -0
  21. package/assets/taiwan-logistics/references/paynow-logistics-api.md +1670 -1670
  22. package/assets/taiwan-logistics/references/payuni-logistics-api.md +712 -712
  23. package/assets/taiwan-logistics/references/pchomepay-logistics-api.md +1154 -1154
  24. package/assets/taiwan-logistics/references/smilepay-logistics-api.md +1332 -1332
  25. package/assets/taiwan-logistics/scripts/core.py +276 -276
  26. package/assets/taiwan-logistics/scripts/generate-logistics-service.py +1248 -1248
  27. package/assets/taiwan-logistics/scripts/recommend.py +370 -364
  28. package/assets/taiwan-logistics/scripts/search.py +127 -127
  29. package/assets/taiwan-logistics/scripts/test_logistics.py +300 -300
  30. package/assets/templates/base/quick-reference.md +74 -74
  31. package/assets/templates/base/skill-content.md +845 -845
  32. package/assets/templates/platforms/agent.json +26 -26
  33. package/assets/templates/platforms/claude.json +26 -26
  34. package/assets/templates/platforms/codebuddy.json +25 -25
  35. package/assets/templates/platforms/codex.json +26 -26
  36. package/assets/templates/platforms/continue.json +25 -25
  37. package/assets/templates/platforms/copilot.json +25 -25
  38. package/assets/templates/platforms/cursor.json +26 -26
  39. package/assets/templates/platforms/gemini.json +25 -25
  40. package/assets/templates/platforms/kiro.json +25 -25
  41. package/assets/templates/platforms/opencode.json +25 -25
  42. package/assets/templates/platforms/qoder.json +25 -25
  43. package/assets/templates/platforms/roocode.json +25 -25
  44. package/assets/templates/platforms/trae.json +25 -25
  45. package/assets/templates/platforms/windsurf.json +25 -25
  46. package/package.json +65 -65
package/README.md CHANGED
@@ -1,132 +1,132 @@
1
- <h1 align="center">taiwan-logistics-skill</h1>
2
-
3
- <h3 align="center">台灣物流 AI 開發技能包</h3>
4
-
5
- <p align="center">
6
- <strong>6 家物流 aggregator + HCT 新竹物流直連 carrier API</strong>
7
- </p>
8
-
9
- <p align="center">
10
- ECPay · NewebPay · PAYUNi · SmilePay · PChomePay · PayNow · HCT 直連
11
- </p>
12
-
13
- <p align="center">
14
- <a href="https://www.npmjs.com/package/taiwan-logistics-skill"><img src="https://img.shields.io/npm/v/taiwan-logistics-skill?style=flat-square&logo=npm" alt="npm version"></a>
15
- <a href="https://www.npmjs.com/package/taiwan-logistics-skill"><img src="https://img.shields.io/npm/dm/taiwan-logistics-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
16
- <img src="https://img.shields.io/badge/providers-7-success?style=flat-square" alt="7 Providers">
17
- <img src="https://img.shields.io/badge/AI%20platforms-14-blue?style=flat-square" alt="14 AI Platforms">
18
- <a href="https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Moksa1123/taiwan-ecommerce-toolkit?style=flat-square" alt="License"></a>
19
- </p>
20
-
21
- <p align="center">
22
- <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>
23
- </p>
24
-
25
- ---
26
-
27
- ## 安裝
28
-
29
- ```bash
30
- npm install -g taiwan-logistics-skill
31
- ```
32
-
33
- ## 快速開始
34
-
35
- ```bash
36
- cd /path/to/your/project
37
-
38
- taiwan-logistics init # 互動式
39
- taiwan-logistics init --ai claude # Claude Code
40
- taiwan-logistics init --ai all # 全部安裝
41
- ```
42
-
43
- 安裝完後,在 AI 助手用自然語言:
44
-
45
- ```
46
- 查詢台北市信義區的 7-11 取貨點,整合 ECPay 物流
47
- 建立 SmilePay 黑貓宅急便冷凍 C2C 訂單,COD 1000 元
48
- PChomePay 7-11 取貨付款,金額 1500 元,notify URL 設好
49
- PayNow 7-11 大宗寄倉,使用 3DES 加密
50
- HCT 直連 API 傳入託運資料,逆物流單獨處理
51
- ```
52
-
53
- ---
54
-
55
- ## 7 家物流服務商
56
-
57
- | 服務商 | 類型 | 加密 / 認證 | 特色 |
58
- |---|---|---|---|
59
- | **ECPay 綠界** | aggregator | MD5 CheckMacValue | 市佔率最高、SDK 完整、7-11/全家/萊爾富/OK/黑貓/宅配通/HCT |
60
- | **NewebPay 藍新** | aggregator | AES-256-CBC + SHA256 | 7-11/全家/萊爾富/OK/黑貓 |
61
- | **PAYUNi 統一** | aggregator | AES-256-GCM + SHA256 | 7-11 常溫/冷凍 + T-Cat 常溫/冷藏/冷凍(溫控配送最完整) |
62
- | **SmilePay 速買配** | aggregator | Verify_key + 加權檢核碼 | Pay_zg 矩陣 51/52/55/56/81/82/83,含逆物流 |
63
- | **PChomePay 拍錢包** | aggregator | HTTP Basic Auth → token | 金物流二合一、Notify IP 113.196.231.190、4 大超商 |
64
- | **PayNow 立吉富** | aggregator | **3DES/ECB/Zero-Padding** | 11 條產品線(含海外配送);不同於金流端 AES |
65
- | **HCT 新竹物流** | **direct carrier API** | 申請後提供金鑰 | 直連 carrier API(vs 透過 aggregator) |
66
-
67
- ## 技能包內容
68
-
69
- ```
70
- taiwan-logistics/
71
- ├── SKILL.md # AI 技能主文檔
72
- ├── EXAMPLES.md # 實戰範例集
73
- ├── references/ # 7 份 API 規格 (~10,300 行)
74
- │ ├── ecpay-logistics-api.md
75
- │ ├── NEWEBPAY_LOGISTICS_REFERENCE.md
76
- │ ├── payuni-logistics-api.md
77
- │ ├── smilepay-logistics-api.md # 1,332 行 / Pay_zg 矩陣
78
- │ ├── pchomepay-logistics-api.md # 1,154 行 / NDJSON 對帳 parser
79
- │ ├── paynow-logistics-api.md # 1,670 行 / 11 產品線
80
- │ └── hct-logistics-api.md # 1,102 行 / 直連 HCT
81
- ├── examples/ # Python 範例
82
- └── data/ # 5 份 CSV
83
- ├── providers.csv # 7 服務商
84
- ├── operations.csv # 30+ API 操作
85
- ├── logistics-types.csv # CVS / Home / 溫控
86
- ├── status-codes.csv # 跨服務商狀態碼
87
- └── field-mappings.csv # 欄位對照
88
- ```
89
-
90
- ## CLI 指令
91
-
92
- ```bash
93
- taiwan-logistics list # 列出 AI 平台
94
- taiwan-logistics info # 技能資訊
95
- taiwan-logistics update # 檢查更新
96
- taiwan-logistics init --force # 覆蓋安裝
97
- taiwan-logistics init --global # 全域安裝
98
- ```
99
-
100
- ## 14 個 AI 平台支援
101
-
102
- Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Roo Code · Gemini · Trae · OpenCode · Continue · CodeBuddy
103
-
104
- ## 物流類型支援矩陣
105
-
106
- | 取貨方式 | 7-11 | 全家 | 萊爾富 | OK | 黑貓 | 海外 | HCT |
107
- |---|---|---|---|---|---|---|---|
108
- | ECPay | ✅ | ✅ | ✅ | ✅ | ✅(常溫) | — | ✅ |
109
- | NewebPay | ✅ | ✅ | ✅ | ✅ | ✅ | — | — |
110
- | PAYUNi | ✅ | — | — | — | ✅(常溫/冷凍/冷藏) | — | — |
111
- | SmilePay | ✅ C2C+B2C | ✅ C2C+B2C | — | — | ✅(COD/PICKUP/逆物流) | — | — |
112
- | PChomePay | ✅ | ✅ | ✅ | ✅ | — | — | — |
113
- | PayNow | ✅(含冷凍) | ✅(含冷凍) | ✅ | ✅ | ✅(宅配 + 店到店) | ✅(7-11) | — |
114
- | HCT 直連 | — | — | — | — | — | — | ✅(直連) |
115
-
116
- ## 相關套件
117
-
118
- 本套件是 **[Taiwan E-Commerce Toolkit](https://github.com/Moksa1123/taiwan-ecommerce-toolkit)** 的一部分:
119
-
120
- - [taiwan-invoice-skill](https://www.npmjs.com/package/taiwan-invoice-skill) — 5 家電子發票
121
- - [taiwan-payment-skill](https://www.npmjs.com/package/taiwan-payment-skill) — 10 家金流
122
-
123
- ## 授權
124
-
125
- [MIT License](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE)
126
-
127
- ---
128
-
129
- <p align="center">
130
- <sub>Made by <strong>Moksa</strong></sub><br>
131
- <sub>service@moksaweb.com</sub>
132
- </p>
1
+ <h1 align="center">taiwan-logistics-skill</h1>
2
+
3
+ <h3 align="center">台灣物流 AI 開發技能包</h3>
4
+
5
+ <p align="center">
6
+ <strong>6 家物流 aggregator + HCT 新竹物流直連 carrier API</strong>
7
+ </p>
8
+
9
+ <p align="center">
10
+ ECPay · NewebPay · PAYUNi · SmilePay · PChomePay · PayNow · HCT 直連
11
+ </p>
12
+
13
+ <p align="center">
14
+ <a href="https://www.npmjs.com/package/taiwan-logistics-skill"><img src="https://img.shields.io/npm/v/taiwan-logistics-skill?style=flat-square&logo=npm" alt="npm version"></a>
15
+ <a href="https://www.npmjs.com/package/taiwan-logistics-skill"><img src="https://img.shields.io/npm/dm/taiwan-logistics-skill?style=flat-square&label=downloads" alt="npm downloads"></a>
16
+ <img src="https://img.shields.io/badge/providers-7-success?style=flat-square" alt="7 Providers">
17
+ <img src="https://img.shields.io/badge/AI%20platforms-14-blue?style=flat-square" alt="14 AI Platforms">
18
+ <a href="https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Moksa1123/taiwan-ecommerce-toolkit?style=flat-square" alt="License"></a>
19
+ </p>
20
+
21
+ <p align="center">
22
+ <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>
23
+ </p>
24
+
25
+ ---
26
+
27
+ ## 安裝
28
+
29
+ ```bash
30
+ npm install -g taiwan-logistics-skill
31
+ ```
32
+
33
+ ## 快速開始
34
+
35
+ ```bash
36
+ cd /path/to/your/project
37
+
38
+ taiwan-logistics init # 互動式
39
+ taiwan-logistics init --ai claude # Claude Code
40
+ taiwan-logistics init --ai all # 全部安裝
41
+ ```
42
+
43
+ 安裝完後,在 AI 助手用自然語言:
44
+
45
+ ```
46
+ 查詢台北市信義區的 7-11 取貨點,整合 ECPay 物流
47
+ 建立 SmilePay 黑貓宅急便冷凍 C2C 訂單,COD 1000 元
48
+ PChomePay 7-11 取貨付款,金額 1500 元,notify URL 設好
49
+ PayNow 7-11 大宗寄倉,使用 3DES 加密
50
+ HCT 直連 API 傳入託運資料,逆物流單獨處理
51
+ ```
52
+
53
+ ---
54
+
55
+ ## 7 家物流服務商
56
+
57
+ | 服務商 | 類型 | 加密 / 認證 | 特色 |
58
+ |---|---|---|---|
59
+ | **ECPay 綠界** | aggregator | MD5 CheckMacValue | 市佔率最高、SDK 完整、7-11/全家/萊爾富/OK/黑貓/宅配通/HCT |
60
+ | **NewebPay 藍新** | aggregator | AES-256-CBC + SHA256 | 7-11/全家/萊爾富/OK/黑貓 |
61
+ | **PAYUNi 統一** | aggregator | AES-256-GCM + SHA256 | 7-11 常溫/冷凍 + T-Cat 常溫/冷藏/冷凍(溫控配送最完整) |
62
+ | **SmilePay 速買配** | aggregator | Verify_key + 加權檢核碼 | Pay_zg 矩陣 51/52/55/56/81/82/83,含逆物流 |
63
+ | **PChomePay 拍錢包** | aggregator | HTTP Basic Auth → token | 金物流二合一、Notify IP 113.196.231.190、4 大超商 |
64
+ | **PayNow 立吉富** | aggregator | **3DES/ECB/Zero-Padding** | 11 條產品線(含海外配送);不同於金流端 AES |
65
+ | **HCT 新竹物流** | **direct carrier API** | 申請後提供金鑰 | 直連 carrier API(vs 透過 aggregator) |
66
+
67
+ ## 技能包內容
68
+
69
+ ```
70
+ taiwan-logistics/
71
+ ├── SKILL.md # AI 技能主文檔
72
+ ├── EXAMPLES.md # 實戰範例集
73
+ ├── references/ # 7 份 API 規格 (~10,300 行)
74
+ │ ├── ecpay-logistics-api.md
75
+ │ ├── NEWEBPAY_LOGISTICS_REFERENCE.md
76
+ │ ├── payuni-logistics-api.md
77
+ │ ├── smilepay-logistics-api.md # 1,332 行 / Pay_zg 矩陣
78
+ │ ├── pchomepay-logistics-api.md # 1,154 行 / NDJSON 對帳 parser
79
+ │ ├── paynow-logistics-api.md # 1,670 行 / 11 產品線
80
+ │ └── hct-logistics-api.md # 1,102 行 / 直連 HCT
81
+ ├── examples/ # Python 範例
82
+ └── data/ # 5 份 CSV
83
+ ├── providers.csv # 7 服務商
84
+ ├── operations.csv # 30+ API 操作
85
+ ├── logistics-types.csv # CVS / Home / 溫控
86
+ ├── status-codes.csv # 跨服務商狀態碼
87
+ └── field-mappings.csv # 欄位對照
88
+ ```
89
+
90
+ ## CLI 指令
91
+
92
+ ```bash
93
+ taiwan-logistics list # 列出 AI 平台
94
+ taiwan-logistics info # 技能資訊
95
+ taiwan-logistics update # 檢查更新
96
+ taiwan-logistics init --force # 覆蓋安裝
97
+ taiwan-logistics init --global # 全域安裝
98
+ ```
99
+
100
+ ## 14 個 AI 平台支援
101
+
102
+ Claude Code · Cursor · Windsurf · Antigravity · GitHub Copilot · Kiro · Codex · Qoder · Roo Code · Gemini · Trae · OpenCode · Continue · CodeBuddy
103
+
104
+ ## 物流類型支援矩陣
105
+
106
+ | 取貨方式 | 7-11 | 全家 | 萊爾富 | OK | 黑貓 | 海外 | HCT |
107
+ |---|---|---|---|---|---|---|---|
108
+ | ECPay | ✅ | ✅ | ✅ | ✅ | ✅(常溫) | — | ✅ |
109
+ | NewebPay | ✅ | ✅ | ✅ | ✅ | ✅ | — | — |
110
+ | PAYUNi | ✅ | — | — | — | ✅(常溫/冷凍/冷藏) | — | — |
111
+ | SmilePay | ✅ C2C+B2C | ✅ C2C+B2C | — | — | ✅(COD/PICKUP/逆物流) | — | — |
112
+ | PChomePay | ✅ | ✅ | ✅ | ✅ | — | — | — |
113
+ | PayNow | ✅(含冷凍) | ✅(含冷凍) | ✅ | ✅ | ✅(宅配 + 店到店) | ✅(7-11) | — |
114
+ | HCT 直連 | — | — | — | — | — | — | ✅(直連) |
115
+
116
+ ## 相關套件
117
+
118
+ 本套件是 **[Taiwan E-Commerce Toolkit](https://github.com/Moksa1123/taiwan-ecommerce-toolkit)** 的一部分:
119
+
120
+ - [taiwan-invoice-skill](https://www.npmjs.com/package/taiwan-invoice-skill) — 5 家電子發票
121
+ - [taiwan-payment-skill](https://www.npmjs.com/package/taiwan-payment-skill) — 10 家金流
122
+
123
+ ## 授權
124
+
125
+ [MIT License](https://github.com/Moksa1123/taiwan-ecommerce-toolkit/blob/main/LICENSE)
126
+
127
+ ---
128
+
129
+ <p align="center">
130
+ <sub>Made by <strong>Moksa</strong></sub><br>
131
+ <sub>service@moksaweb.com</sub>
132
+ </p>
@@ -1,137 +1,147 @@
1
- # CLAUDE.md
2
-
3
- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
-
5
- ## Project Overview
6
-
7
- Taiwan Logistics Skill is an AI-powered toolkit for Taiwan logistics integration, providing API documentation, code examples, and scripts for major logistics platforms. It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
8
-
9
- **Supported Providers:** `ecpay`, `newebpay`, `payuni`, `smilepay`, `pchomepay`, `paynow`, `hct_direct`
10
-
11
- ## Available Scripts
12
-
13
- ```bash
14
- # Search API documentation (BM25)
15
- python3 taiwan-logistics/scripts/search.py "<query>" [--domain <domain>]
16
-
17
- # Recommend logistics provider
18
- python3 taiwan-logistics/scripts/recommend.py "<requirements>"
19
-
20
- # Test API connectivity
21
- python3 taiwan-logistics/scripts/test_logistics.py [--platform <platform>]
22
-
23
- # Generate logistics service code
24
- python3 taiwan-logistics/scripts/generate-logistics-service.py <Platform> --output <ts|py>
25
- ```
26
-
27
- ## Architecture
28
-
29
- ```
30
- taiwan-logistics/ # Source of Truth
31
- ├── SKILL.md # Main skill documentation
32
- ├── EXAMPLES.md # Code examples and patterns
33
- ├── references/ # API documentation
34
- │ ├── ecpay-logistics-api.md
35
- │ ├── NEWEBPAY_LOGISTICS_REFERENCE.md
36
- │ ├── payuni-logistics-api.md
37
- │ ├── smilepay-logistics-api.md # NEW (Phase 4): Pay_zg matrix
38
- │ ├── pchomepay-logistics-api.md # NEW (Phase 4): 金物流二合一
39
- │ ├── paynow-logistics-api.md # NEW (Phase 4): 11 product lines, 3DES/ECB
40
- │ └── hct-logistics-api.md # NEW (Phase 4): HCT 直連 carrier API
41
- ├── examples/ # Python examples per provider
42
- └── data/ # Data-driven CSVs
43
- ├── providers.csv # 7+ providers/carriers
44
- ├── operations.csv # cross-provider API operations
45
- ├── logistics-types.csv # CVS/Home/temp variants
46
- ├── status-codes.csv # vendor-specific status codes
47
- └── field-mappings.csv # cross-provider field mapping
48
-
49
- logistics-cli/ # CLI installer (taiwan-logistics-skill on npm)
50
- ├── src/
51
- │ ├── commands/init.ts # Install command with template generation
52
- │ ├── utils/template.ts # Template rendering engine
53
- └── assets/ # Bundled assets
54
- ├── taiwan-logistics/ # Copy of taiwan-logistics/
55
- └── templates/
56
- ├── base/ # Base templates (skill-content.md, quick-reference.md)
57
- └── platforms/ # Platform configs (14 platforms)
58
-
59
- .claude/skills/taiwan-logistics/ # Claude Code skill (generated by CLI)
60
- ```
61
-
62
- ## Sync Rules
63
-
64
- **Source of Truth:** `taiwan-logistics/`
65
-
66
- When modifying files:
67
-
68
- 1. **Skill Content** - Edit in `taiwan-logistics/`:
69
- - `SKILL.md` - Main documentation
70
- - `EXAMPLES.md` - Code examples
71
- - `references/*.md` - API documentation
72
- - `scripts/*.py` - Utility scripts
73
- - `data/*.csv` - Data files
74
-
75
- 2. **Templates** - Edit in `logistics-cli/assets/templates/`:
76
- - `base/skill-content.md` - Common skill content
77
- - `base/quick-reference.md` - Quick reference (Claude only)
78
- - `platforms/*.json` - Platform-specific configs (14 platforms)
79
-
80
- 3. **CLI Assets** - Run sync before publishing:
81
- ```bash
82
- cp -r taiwan-logistics/* logistics-cli/assets/taiwan-logistics/
83
- ```
84
-
85
- ## Supported AI Platforms
86
-
87
- | Platform | Folder | Install Type |
88
- |-------------|-------------|--------------|
89
- | Claude Code | `.claude` | full |
90
- | Cursor | `.cursor` | full |
91
- | Windsurf | `.windsurf` | full |
92
- | Antigravity | `.agent` | full |
93
- | Copilot | `.github` | full |
94
- | Kiro | `.kiro` | full |
95
- | Codex | `.codex` | full |
96
- | Qoder | `.qoder` | full |
97
- | Roo Code | `.roo` | full |
98
- | Gemini | `.gemini` | full |
99
- | Trae | `.trae` | full |
100
- | OpenCode | `.opencode` | full |
101
- | Continue | `.continue` | full |
102
- | CodeBuddy | `.codebuddy`| full |
103
-
104
- ## Prerequisites
105
-
106
- - Node.js 18+ (for CLI)
107
- - Python 3.x (for scripts, no external dependencies)
108
-
109
- ## Encryption Methods
110
-
111
- | Provider | Encryption | Notes |
112
- |---|---|---|
113
- | ECPay 綠界 | MD5 CheckMacValue | Sort params + HashKey/HashIV |
114
- | NewebPay 藍新 | AES-256-CBC + SHA256 | Same as MPG payment |
115
- | PAYUNi 統一 | AES-256-GCM + SHA256 | Append 16-byte tag |
116
- | SmilePay 速買配 | Verify_key + Mid_smilepay 加權檢核碼 | No AES; shared secret |
117
- | PChomePay 拍錢包 | HTTP Basic Auth → 8h pcpay-token | Same as payment side |
118
- | PayNow 立吉富 | **3DES (TripleDES) / ECB / Zero-Padding** | 24-byte Key + 8-byte IV; **不同於金流端的動態 AES-256** |
119
- | HCT 直連 | 自訂加密(金鑰申請後提供) | C# sample code only |
120
-
121
- ## Git Workflow
122
-
123
- Never push directly to `main`. Always:
124
-
125
- 1. Create a new branch: `git checkout -b feat/...` or `fix/...`
126
- 2. Commit changes
127
- 3. Push branch: `git push -u origin <branch>`
128
- 4. Create PR: `gh pr create`
129
-
130
- ## Related Projects
131
-
132
- - **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego, ezPay, PayNow)
133
- - **Taiwan Payment Skill** - Payment integration (10 providers including ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline, LINE Pay, TapPay)
134
-
135
- ---
136
-
137
- **Last Updated**: 2026-05-07 (Phase 4: +4 logistics providers — SmilePay, PChomePay, PayNow, HCT direct)
1
+ # CLAUDE.md
2
+
3
+ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+ ## Project Overview
6
+
7
+ Taiwan Logistics Skill is an AI-powered toolkit for Taiwan logistics integration, providing API documentation, code examples, and scripts for major logistics platforms. It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).
8
+
9
+ **Supported Providers:** `ecpay`, `newebpay`, `payuni`, `smilepay`, `pchomepay`, `paynow`, `ezship`, `lalamove`, `hct_direct`
10
+
11
+ **No public API(僅列於 providers.csv 供查詢,`api_available=false`):** 黑貓 t-cat、嘉里大榮、宅配通、中華郵政、7-11 交貨便/賣貨便、全家好賣+、萊爾富、OK、蝦皮店到店。原因與替代路徑見 `references/carrier-direct-access.md`。
12
+
13
+ ## Available Scripts
14
+
15
+ ```bash
16
+ # Search API documentation (BM25)
17
+ python3 taiwan-logistics/scripts/search.py "<query>" [--domain <domain>]
18
+
19
+ # Recommend logistics provider
20
+ python3 taiwan-logistics/scripts/recommend.py "<requirements>"
21
+
22
+ # Test API connectivity
23
+ python3 taiwan-logistics/scripts/test_logistics.py [--platform <platform>]
24
+
25
+ # Generate logistics service code
26
+ python3 taiwan-logistics/scripts/generate-logistics-service.py <Platform> --output <ts|py>
27
+ ```
28
+
29
+ ## Architecture
30
+
31
+ ```
32
+ taiwan-logistics/ # Source of Truth
33
+ ├── SKILL.md # Main skill documentation
34
+ ├── EXAMPLES.md # Code examples and patterns
35
+ ├── references/ # API documentation
36
+ │ ├── ecpay-logistics-api.md
37
+ │ ├── NEWEBPAY_LOGISTICS_REFERENCE.md
38
+ │ ├── payuni-logistics-api.md
39
+ │ ├── smilepay-logistics-api.md # NEW (Phase 4): Pay_zg matrix
40
+ │ ├── pchomepay-logistics-api.md # NEW (Phase 4): 金物流二合一
41
+ │ ├── paynow-logistics-api.md # NEW (Phase 4): 11 product lines, 3DES/ECB
42
+ │ └── hct-logistics-api.md # NEW (Phase 4): HCT 直連 carrier API
43
+ ├── examples/ # Python examples per provider
44
+ └── data/ # Data-driven CSVs
45
+ ├── providers.csv # 9 可串接 + 10 僅供查詢(含 doc_access 分級)
46
+ ├── operations.csv # cross-provider API operations
47
+ ├── logistics-types.csv # CVS/Home/temp variants
48
+ ├── status-codes.csv # vendor-specific status codes
49
+ └── field-mappings.csv # cross-provider field mapping
50
+
51
+ logistics-cli/ # CLI installer (taiwan-logistics-skill on npm)
52
+ ├── src/
53
+ │ ├── commands/init.ts # Install command with template generation
54
+ │ ├── utils/template.ts # Template rendering engine
55
+ └── assets/ # Bundled assets
56
+ ├── taiwan-logistics/ # Copy of taiwan-logistics/
57
+ └── templates/
58
+ ├── base/ # Base templates (skill-content.md, quick-reference.md)
59
+ └── platforms/ # Platform configs (14 platforms)
60
+
61
+ .claude/skills/taiwan-logistics/ # Claude Code skill (generated by CLI)
62
+ ```
63
+
64
+ ## Sync Rules
65
+
66
+ **Source of Truth:** `taiwan-logistics/`
67
+
68
+ When modifying files:
69
+
70
+ 1. **Skill Content** - Edit in `taiwan-logistics/`:
71
+ - `SKILL.md` - Main documentation
72
+ - `EXAMPLES.md` - Code examples
73
+ - `references/*.md` - API documentation
74
+ - `scripts/*.py` - Utility scripts
75
+ - `data/*.csv` - Data files
76
+
77
+ 2. **Templates** - Edit in `logistics-cli/assets/templates/`:
78
+ - `base/skill-content.md` - Common skill content
79
+ - `base/quick-reference.md` - Quick reference (Claude only)
80
+ - `platforms/*.json` - Platform-specific configs (14 platforms)
81
+
82
+ 3. **CLI Assets** - 自動同步,無需手動複製:
83
+ - `<cli>/scripts/build.js` 會在打包前呼叫 `scripts/sync-assets.mjs`,
84
+ 因此 `npm run build` 與 `npm publish`(透過 prepublishOnly)都會自動帶到最新內容
85
+ - 發布流程另以 `node scripts/sync-assets.mjs --check` 驗證,落差會擋下發布
86
+
87
+ ```bash
88
+ node scripts/sync-assets.mjs # 手動同步全部
89
+ node scripts/sync-assets.mjs --check # 只檢查,有落差 exit 1
90
+ ```
91
+
92
+ > assets 會隨 npm publish 一起發布(package.json 的 `files` 含 `assets`),
93
+ > 過去忘記同步會靜默發出過期的 skill 內容,因此改為自動化。
94
+
95
+ ## Supported AI Platforms
96
+
97
+ | Platform | Folder | Install Type |
98
+ |-------------|-------------|--------------|
99
+ | Claude Code | `.claude` | full |
100
+ | Cursor | `.cursor` | full |
101
+ | Windsurf | `.windsurf` | full |
102
+ | Antigravity | `.agent` | full |
103
+ | Copilot | `.github` | full |
104
+ | Kiro | `.kiro` | full |
105
+ | Codex | `.codex` | full |
106
+ | Qoder | `.qoder` | full |
107
+ | Roo Code | `.roo` | full |
108
+ | Gemini | `.gemini` | full |
109
+ | Trae | `.trae` | full |
110
+ | OpenCode | `.opencode` | full |
111
+ | Continue | `.continue` | full |
112
+ | CodeBuddy | `.codebuddy`| full |
113
+
114
+ ## Prerequisites
115
+
116
+ - Node.js 18+ (for CLI)
117
+ - Python 3.x (for scripts, no external dependencies)
118
+
119
+ ## Encryption Methods
120
+
121
+ | Provider | Encryption | Notes |
122
+ |---|---|---|
123
+ | ECPay 綠界 | MD5 CheckMacValue | Sort params + HashKey/HashIV |
124
+ | NewebPay 藍新 | AES-256-CBC + SHA256 | Same as MPG payment |
125
+ | PAYUNi 統一 | AES-256-GCM + SHA256 | Append 16-byte tag |
126
+ | SmilePay 速買配 | Verify_key + Mid_smilepay 加權檢核碼 | No AES; shared secret |
127
+ | PChomePay 拍錢包 | HTTP Basic Auth → 8h pcpay-token | Same as payment side |
128
+ | PayNow 立吉富 | **3DES (TripleDES) / ECB / Zero-Padding** | 24-byte Key + 8-byte IV; **不同於金流端的動態 AES-256** |
129
+ | HCT 直連 | 自訂加密(金鑰申請後提供) | C# sample code only |
130
+
131
+ ## Git Workflow
132
+
133
+ Never push directly to `main`. Always:
134
+
135
+ 1. Create a new branch: `git checkout -b feat/...` or `fix/...`
136
+ 2. Commit changes
137
+ 3. Push branch: `git push -u origin <branch>`
138
+ 4. Create PR: `gh pr create`
139
+
140
+ ## Related Projects
141
+
142
+ - **Taiwan Invoice Skill** - E-Invoice integration (ECPay, SmilePay, Amego, ezPay, PayNow)
143
+ - **Taiwan Payment Skill** - Payment integration (14 providers: ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, ezPay, PayNow, Shopline, LINE Pay, TapPay, O'Pay, JKOPAY, SunPay, GoMyPay)
144
+
145
+ ---
146
+
147
+ **Last Updated**: 2026-05-07 (Phase 4: +4 logistics providers — SmilePay, PChomePay, PayNow, HCT direct)