taiwan-logistics-skill 1.2.0 → 1.2.1
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.
- package/README.md +132 -190
- package/assets/taiwan-logistics/CLAUDE.md +137 -137
- package/assets/taiwan-logistics/references/hct-logistics-api.md +1102 -1102
- package/assets/taiwan-logistics/references/paynow-logistics-api.md +1670 -1670
- package/assets/taiwan-logistics/references/pchomepay-logistics-api.md +1154 -1154
- package/assets/taiwan-logistics/references/smilepay-logistics-api.md +1332 -1332
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,190 +1,132 @@
|
|
|
1
|
-
<h1 align="center">taiwan-logistics-skill</h1>
|
|
2
|
-
|
|
3
|
-
<
|
|
4
|
-
|
|
5
|
-
<p align="center">
|
|
6
|
-
<
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
</p>
|
|
12
|
-
|
|
13
|
-
<p align="center">
|
|
14
|
-
<a href="https://
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
---
|
|
26
|
-
|
|
27
|
-
##
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
taiwan-logistics init
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
#
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
#
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
#
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
|
113
|
-
|
|
114
|
-
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
| 服務商 | 加密方式 | API 風格 | 特色 |
|
|
134
|
-
|--------|---------|---------|------|
|
|
135
|
-
| **綠界 ECPay** | SHA256 | Form POST | 市佔率最高,穩定性佳,完整文檔 |
|
|
136
|
-
| **藍新 NewebPay** | AES-256-CBC + SHA256 | Form POST + AES | 支援多種物流方式 |
|
|
137
|
-
| **統一 PAYUNi** | AES-256-GCM + SHA256 | RESTful JSON | 統一集團,RESTful 設計 |
|
|
138
|
-
|
|
139
|
-
---
|
|
140
|
-
|
|
141
|
-
## 功能特色
|
|
142
|
-
|
|
143
|
-
- **完整 API 文檔** - ECPay、NewebPay、PAYUNi 詳細規格
|
|
144
|
-
- **代碼範例** - TypeScript/Python 完整可執行範例
|
|
145
|
-
- **加密實作指南** - SHA256、AES-256-CBC、AES-256-GCM
|
|
146
|
-
- **14 個 AI 平台** - 支援主流 AI 編程助手
|
|
147
|
-
|
|
148
|
-
---
|
|
149
|
-
|
|
150
|
-
## 物流方式支援
|
|
151
|
-
|
|
152
|
-
### 宅配
|
|
153
|
-
- 宅配到府、宅配貨到付款
|
|
154
|
-
|
|
155
|
-
### 超商取貨
|
|
156
|
-
- 7-ELEVEN 取貨、全家取貨、OK超商取貨、萊爾富取貨
|
|
157
|
-
- 超商取貨付款
|
|
158
|
-
|
|
159
|
-
### 其他
|
|
160
|
-
- 冷鏈宅配、國際物流
|
|
161
|
-
|
|
162
|
-
---
|
|
163
|
-
|
|
164
|
-
## 開發要求
|
|
165
|
-
|
|
166
|
-
- **Node.js** >= 18.0.0 (CLI 工具)
|
|
167
|
-
- **Python** >= 3.x (智能腳本,無外部依賴)
|
|
168
|
-
|
|
169
|
-
---
|
|
170
|
-
|
|
171
|
-
## 授權
|
|
172
|
-
|
|
173
|
-
本專案採用 [MIT License](https://opensource.org/licenses/MIT) 授權。
|
|
174
|
-
|
|
175
|
-
---
|
|
176
|
-
|
|
177
|
-
## 作者
|
|
178
|
-
|
|
179
|
-
由 [Moksa](https://github.com/Moksa1123) 開發維護。
|
|
180
|
-
|
|
181
|
-
---
|
|
182
|
-
|
|
183
|
-
## 相關專案
|
|
184
|
-
|
|
185
|
-
- [taiwan-logistics-skill](https://github.com/Moksa1123/taiwan-ecommerce-toolkit) - 台灣電子發票整合
|
|
186
|
-
- [taiwan-payment-skill](https://github.com/Moksa1123/taiwan-payment) - 台灣金流整合
|
|
187
|
-
|
|
188
|
-
---
|
|
189
|
-
|
|
190
|
-
<p align="center">Made for Taiwan developers</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,137 @@
|
|
|
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`, `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)
|