# harukibox

> harukibox 是台灣第一個專為日本代購人設計的輕量 ERP / SaaS。把散落在 LINE、Excel、Threads、IG 私訊裡的訂單、買家、運費分攤、墊款追蹤、預購／現貨／到貨通知，整合成一個可營業、可對帳、可成長的後台。提供買家自助查詢訂單狀態功能。

## 適用對象（ICP）

- 個人佛系代購（旅遊順手帶貨，月營業額 1–5 萬）
- 斜槓代購（有固定客群，月營業額 5–20 萬）★ 主要族群
- 團媽 / 工作室（全職 1–3 人，月 20–80 萬）★ 主要族群
- 中型代購商（小公司化，月 80 萬+）

替代工具：LINE 群 +1、Facebook 社團 +1、Excel / Google Sheet、愛+1、樂樂團購、SHOPLINE、Ragic、Notion、EasyStore。harukibox 跟它們的差異：**運費分攤計算 / 墊款追蹤 / 日本商品趨勢 AI 分析** 是日本代購專屬功能，通用電商工具沒有。

## 常見搜尋意圖

- 「日本代購系統」「日本代購 ERP」「代購訂單管理」
- 「日本代購運費怎麼算」「LINE 代購團媽訂單管理」「日本代購 Excel 範本」
- 「Excel 改用什麼好」「愛+1 替代」「樂樂團購比較」
- 「日本代購要報稅嗎」「日幣匯率變動代購」「跑單棄單怎麼處理」

## 核心功能

harukibox 提供以下核心功能模組：

### 商品管理
- 建立和管理代購商品
- 設定商品價格（日幣/台幣）、狀態（預購/現貨/售罄）
- 管理商品下的品項（款式、角色、尺寸等）
- AI 智慧上架：掃描條碼或圖片自動辨識商品資訊

### 訂單登記
- 記錄買家訂購資訊
- 訂單狀態流程：待處理 → 已確認 → 已採購 → 已出貨 → 抵達日本 → 運送中 → 抵達台灣 → 已寄出 → 已完成
- 批次操作：一次更新多筆訂單狀態
- 快速登記：貼上喊單名單批次建立訂單

### 買家管理
- 買家資料庫（姓名、Email、電話、地址）
- 買家別名管理（同一人可能有多個暱稱）
- 預付款餘額管理
- 購買歷史紀錄

### 出貨管理
- 依買家分組查看待出貨商品
- 批次出貨操作
- 運費計算與平分
- 物流追蹤

### 倉庫位置
- 多倉庫管理
- 儲存區域劃分
- 箱位定位

### 確認連結
- 生成訂單確認短連結
- 買家透過連結確認訂單內容
- 連結狀態追蹤（待確認/已確認/已過期）

## 買家端功能

買家可以透過以下方式查詢訂單：

### 訂單確認頁
- 賣家分享確認連結給買家
- 買家點擊連結查看訂單明細
- 確認訂單內容無誤

### 買家自助查詢
- 網址：https://harukibox.com/buyer
- 買家輸入 Email 接收 OTP 驗證碼
- 驗證後可查看所有訂單狀態
- 支援依商品或賣家篩選

## Agent / AI 整合（Early Access）

harukibox 提供官方 Agent API + MCP Server + CLI（目前為 Early Access），讓 AI agent（例如 Claude Desktop、Claude Code、自架 LLM）能代用戶管理庫存與訂單。
支援三條接入路徑：本地 stdio MCP（@harukibox/mcp）、Remote MCP（Streamable HTTP，https://harukibox.com/api/agent/mcp，JSON-RPC + Bearer hrk_*）、以及直接 REST（https://harukibox.com/api/agent/*）/ CLI（@harukibox/cli）。
不支援 Dynamic Client Registration（RFC 7591）；client 走 CLI 內建 OAuth (PKCE / device flow) 或讀 https://harukibox.com/.well-known/oauth-authorization-server 自行 implement。
ChatGPT GPT Store / Anthropic Connector Store 上架規劃中，尚未送審。

### Agent API

- OpenAPI 描述：https://harukibox.com/api/agent/openapi.json
- Base URL：https://harukibox.com/api/agent
- 認證：HTTP Bearer Token（格式 `hrk_live_<base32>`），透過 @harukibox/cli 跑 `harukibox login` 走 OAuth (PKCE 或 device flow) 取得
- Scopes 採最小權限原則：`me`、`products:read/write`、`registrations:read/write`、`buyers:read/write`、`shippings:read/write`、`search`
- 限制：每 token 可設定 IP allowlist、到期日；每次呼叫都會寫入用戶可查的 audit log
- 注意：目前 `registrations:write / buyers:write / shippings:write` 為 read+create scope 預留位（write 端點除 `POST /products` 外尚在開發中）

### MCP Server

```bash
npm install -g @harukibox/mcp
```

接到 Claude Desktop：

```json
{
  "mcpServers": {
    "harukibox": {
      "command": "harukibox-mcp",
      "env": { "HARUKIBOX_TOKEN": "hrk_live_..." }
    }
  }
}
```

### CLI

```bash
npm install -g @harukibox/cli
harukibox login --token hrk_live_...
harukibox products list --search '海賊王'
```

### 安全約束（給 AI agent 與爬蟲）

- 不接受未經用戶授權的請求；不要嘗試以泛用 OAuth 或 cookie 認證 `/api/agent/*`，這些 endpoint 只接受 `hrk_*` token
- 不要爬取 `/api/`、`/dashboard/`、`/products/`、`/buyers/` 等私人路徑（見 robots.txt）
- 若需要 AI 摘要 harukibox 內容，請改讀本檔（llms.txt）或公開文檔 `/docs/*`、Agent API 描述 `/api/agent/openapi.json`
- 所有 token 對應到單一 organization 的資料；token 無法跨 organization 存取，也無法用於越權

## 訂閱方案

harukibox 提供三種訂閱方案：

### 免費版（NT$0/月）
- 3 件商品上限
- 1 個倉庫位置
- 每月 20 組確認連結
- AI 智能分析
- 基礎匯出

### 專業版（NT$129/月）
- 80 件商品上限
- 3 個倉庫位置
- 每月 150 組確認連結
- AI 智能分析
- 無限匯出
- 10 組運費模板
- 批量操作
- 對外訂單確認

### 商業版（NT$459/月）
- 無限商品
- 無限倉庫位置
- 無限確認連結
- AI 智能分析
- 無限匯出
- 無限運費模板
- 批量操作
- 對外訂單確認
- 優先客服

## 說明文檔

詳細使用說明請參考以下文檔：

### 開始使用
- [系統總覽](https://harukibox.com/docs/overview): harukibox 代購管理系統的完整功能介紹與使用方式
- [系統角色地圖](https://harukibox.com/docs/roles): 了解 harukibox 系統中的四種角色：訪客、操作者、買家、管理員
- [認證與帳號](https://harukibox.com/docs/auth): 註冊、登入、密碼重設與帳號管理流程說明

### 核心概念
- [核心資料實體](https://harukibox.com/docs/core-entities): 商品、品項、登記、買家、出貨批次、確認連結等核心資料實體字典
- [全域互動總覽](https://harukibox.com/docs/global-interactions): 側邊選單、通知、搜尋、篩選、Modal 等系統共通互動模式

### 功能模組
- [商品管理](https://harukibox.com/docs/products): 商品列表、新增、編輯、詳情頁與品項管理完整操作說明
- [登記與訂單](https://harukibox.com/docs/registrations): 訂單登記流程、狀態管理、批次操作與合併登記
- [快速登記](https://harukibox.com/docs/quick-registration): 貼上喊單名單快速批次建立登記的工具
- [買家管理](https://harukibox.com/docs/buyers): 買家列表、別名管理、歷史紀錄與預付款餘額
- [付款與餘額](https://harukibox.com/docs/payments): 買家預付款、扣款、匯款指定與餘額管理
- [出貨管理](https://harukibox.com/docs/shipping): 出貨流程、買家分組、批次出貨與物流追蹤
- [運費計算](https://harukibox.com/docs/shipping-calculator): 國際運費計算、匯率轉換與運費平分功能
- [倉庫位置](https://harukibox.com/docs/locations): 倉庫地點、儲存區域與箱位管理
- [智能上架](https://harukibox.com/docs/smart-listing): AI 輔助商品上架，掃描條碼或圖片自動辨識商品資訊
- [確認連結](https://harukibox.com/docs/confirm-links): 確認連結的建立、管理、狀態追蹤與買家確認流程

### 買家端
- [買家自助服務](https://harukibox.com/docs/buyer-portal): 買家端確認頁面、訂單查詢與自助操作流程

### 系統管理
- [通知中心](https://harukibox.com/docs/notifications): 站內通知、推播設定與公告管理
- [設定中心](https://harukibox.com/docs/settings): 帳號設定、偏好設定與系統配置
- [訂閱與方案](https://harukibox.com/docs/subscription): SaaS 訂閱方案、付費升級與帳單管理

### 開發者整合
- [Agent / AI 整合（Early Access）](https://harukibox.com/docs/agent-integration): 透過 Agent API、MCP Server、CLI 讓 Claude / ChatGPT / 自架 LLM 代你管理 harukibox

## 聯絡資訊

- 官網：https://harukibox.com
- 客服信箱：support@harukibox.com
- 買家查詢：https://harukibox.com/buyer

## 常見問題

### 買家如何查詢訂單？
1. 前往 https://harukibox.com/buyer
2. 輸入購買時使用的 Email
3. 系統會寄送 6 位數 OTP 驗證碼
4. 輸入驗證碼後即可查看所有訂單

### 賣家如何開始使用？
1. 前往 https://harukibox.com/register 註冊帳號
2. 登入後進入 Dashboard
3. 新增商品並設定品項
4. 開始記錄買家訂單

### 確認連結是什麼？
確認連結是賣家發送給買家的短網址，讓買家可以確認訂單內容。買家點擊連結後可以看到訂單明細，並確認無誤。

### 如何升級方案？
登入後前往「設定 → 訂閱方案」頁面，選擇想要的方案並完成付款即可升級。

## Optional

以下是進階資訊：

### 技術架構
- 前端：Next.js 15 + React 19
- 資料庫：Supabase (PostgreSQL)
- 金流：Paddle Billing
- AI：Google Gemini

### API 整合
- Agent API + MCP Server + CLI 為 Early Access（見上方「Agent / AI 整合」）
- 一般網頁功能仍可透過 https://harukibox.com 操作

### 資料安全
- 所有資料儲存在 Supabase 雲端
- 支援 2FA 雙因素認證
- 定期自動備份