Crystal ERP — 項目計劃

更新日期：2026-03-28 文檔定位：docs/ 目錄中的唯一活躍 roadmap；已完成階段的實施細節、審計與修復記錄已移至 docs/archive/。

系統概覽

Crystal ERP 是一個面向水晶原石與加工品銷售的輕量 ERP，核心目標是統一管理庫存、批次、銷售事實、權限控制與線下物理作業。

設計原則

原則	說明
Free-first	優先使用免費方案：Supabase Free、Vercel Free、Cloudflare R2
Simple-first	每個 Phase 交付可用 MVP，不追求完美後再上線
JPY-as-base	所有財務計算以 JPY 為基準貨幣，外幣匯率快照鎖定
Platform-agnostic	平台抽象為主數據，新增平台以數據配置為主
Append-only facts	銷售記錄、訂單記錄保持 append-only，保留審計追溯能力
Offline OK	掃碼、標籤列印等本地功能不依賴雲端服務
Raw/Crafted Split	原石與加工品分離管理，但共用圖片、標籤、日誌與平台基礎設施

業務模型

SKU：1 SKU = 1 件庫存

原石與加工品都採用唯一 SKU，不復用、不做數量型庫存。

原石 SKU：

BN-BR-MC-0001-001
│   │   │    │   └── 批次序號
│   │   │    └────── 批次號
│   │   └─────────── 品類
│   └─────────────── 國家
└─────────────────── 系統前綴

加工品 SKU：

BN-GS-AA-202601-001
│  │  │    │      └── 批次內序號
│  │  │    └───────── 批次號
│  │  └────────────── 保留字段（初期固定 AA）
│  └───────────────── 工藝類型
└──────────────────── 系統前綴

銷售渠道：1 SKU → 1 Channel

每個 SKU 同一時間只在一個渠道銷售，避免超賣與同步衝突。

財務：Append-only

銷售記錄不可覆寫；退款與沖正以新事實記錄寫入，不直接改歷史值。

技術架構

ERP

層級	技術
Frontend	Vue 3 + Vite + TypeScript + Tailwind + daisyUI
Backend	Supabase Edge Functions + 少量 Vercel Functions（AI Gateway 規劃中）
Database	Supabase (PostgreSQL + Auth + RLS)
Storage	Cloudflare R2
Dev	Docker + Supabase CLI

獨立站

層級	技術
Framework	Next.js + Prisma
Database	Neon Database
Hosting	Vercel

系統結構

Website (Next.js + Neon DB)
        │
        │  API / Adapter
        ▼
 ERP (Vue + Supabase)
        │
        ├── Supabase Auth + RLS
        ├── Edge Functions
        └── Cloudflare R2（圖片）

ERP 是庫存與財務的唯一權威來源（Source of Truth）。外部平台與獨立站只做同步與展示，不直接成為記賬來源。

核心數據表

表名	說明
`inventory_items`	原石庫存
`crafted_items`	加工品庫存
`batches`	批次進貨記錄
`sales_records`	append-only 銷售事實
`platforms`	平台主數據（Etsy / Mercari / Catawiki / Website 等）
`craft_types`	加工品工藝類型主數據
`exchange_rates_history`	匯率參考與快照緩存
`inventory_logs`	庫存與操作日誌
`user_profiles` / `system_settings`	Auth、角色與系統設置
`orders` / `order_items`	訂單主表與明細（Phase 0.5）
`market_price_snapshots`	市場定價數據（Phase 1.0+）

當前系統能力

維度	已完成	待補齊
原石庫存	CRUD、自動 SKU、圖片上傳、Lightbox、篩選搜索、批量封存/列印、QR 掃碼	無訂單綁定、無批量入庫
加工品庫存	獨立 `crafted_items`、工藝類型、獨立 SKU、圖片/列印/掃碼復用、銷售記錄接入	無訂單與報關串接
財務與匯率	日匯率/月均匯率、JPY 換算、匯率快照鎖定、毛利計算、append-only `sales_records`	無運費/包材/訂單層利潤
權限與安全	Supabase Auth、invite-only、RBAC、RLS、Settings 用戶管理	staff 目前僅做前端敏感欄位遮蔽，未做後端欄位級脫敏
營運介面	Dashboard、Logs、Settings、主數據管理、密碼修改	無進階圖表與經營分析
平台整合	手動平台主數據、平台費率、已售手續費自動計算	無 Etsy OAuth / 商品同步 / 訂單回拉
線下作業	dtpweb 標籤列印、列印預覽、打印助手檢測、移動端掃碼	無出貨單/報關單流程

開發路線

Phase 0.3 — 體驗完善與平台主數據 `✅ 已完成`

目標：補齊日常操作中的 UX 短板，為後續平台集成打好數據基礎。

[x] platforms 表：code / name / fee_rate / active 等字段
[x] 平台管理頁 MasterPlatforms.vue
[x] 已售 Modal 自動計算手續費（選擇平台後讀取費率）
[x] 圖片 Lightbox（vue-easy-lightbox，支持手勢與縮放）

Phase 0.3.1 — 搜索、批量操作與平台補齊 `✅ 已完成`

目標：補齊 Phase 0.3 遺漏內容，讓列表操作足夠支撐日常使用。

[x] 新增 Catawiki 平台
[x] 列表頁簡易搜索（SKU / 名稱模糊匹配）
[x] 產地 / 品種篩選與記憶
[x] 批量封存與批量列印

Phase 0.4 — 物理連接與標籤打印 `✅ 已完成`

目標：為每件庫存建立可掃描的物理標識，完成「系統 ↔ 實物」錨定。

架構（dtpweb SDK 直連，無需 Python 橋接）：

Browser (Vue + dtpweb) ──打印助手(localhost)──▶ Detonger DT60

前置條件：安裝 DT60 Windows 驅動（內含 dtpweb 打印助手常駐服務）

標籤打印

[x] 封裝 src/lib/printer.ts：initPrinter() / getPrinterList() / printLabel() / previewLabel() / printLabels()
[x] 40×30mm 與 20×10mm 標籤模板
[x] ItemDetail 單張列印（含預覽 Modal、打印機選擇、份數/濃度）
[x] ItemList 批量勾選 → 批量列印
[x] 打印助手檢測與離線提示

掃碼入口

[x] 列表頁快捷掃碼入口
[x] 移動端攝像頭掃碼 → 跳轉商品詳情
[x] README 補充局域網開發訪問說明

Phase 0.4.1 — 加工品庫存模組 `✅ 已完成`

目標：將加工品與原石分離管理，但共用圖片、列印、掃碼與財務基礎設施。

[x] craft_types / crafted_items / crafted_item_images 表與相關 migration
[x] sales_records 擴展為同時支援原石與加工品
[x] generate_next_crafted_sku() 與 crafted_items_view
[x] CraftedItemList.vue / CraftedItemCreate.vue / CraftedItemDetail.vue
[x] MasterCraftTypes.vue
[x] 加工品頁面接入圖片、列印、掃碼與操作日誌

Phase 0.4.2 — 登入系統與 RBAC `✅ 已完成`

目標：引入正式登入流程與角色權限控制，讓 ERP 可以進入實際內部使用。

[x] Supabase Auth 登入流程與 LoginView.vue
[x] useAuth.ts 全局認證狀態管理與路由守衛
[x] user_profiles / system_settings 表與 RLS 策略重寫
[x] 角色：owner / manager / staff
[x] SettingsView.vue 用戶邀請、角色調整、停用/啟用
[x] invite-only 註冊模式與初始 owner 建立腳本 create-admin.ts

Phase 0.4.3 — Dashboard 與導航重構 `✅ 已完成`

目標：把系統從單一庫存頁升級為具備經營入口的 ERP 首頁。

[x] DashboardView.vue：月銷售額、原石數、加工品數、庫存總值、平均毛利率
[x] KPI 顯示配置與拖拽排序
[x] 導航重構：Dashboard / 庫存 / 主數據 / 日誌 / 系統設置
[x] LogsView.vue 操作日誌搜索與詳情展開
[x] staff 專用設置頁（僅密碼修改）
[x] Crafted 頁面與原石頁面 UI/操作對齊修復

Phase 0.5 — 訂單與履約基礎 `⬜ 待開始` `~2 週`

目標：引入「訂單」概念，將散落在 sales_records、inventory_items、crafted_items 中的成交信息統一管理。這是從「庫存系統」到「ERP」的關鍵轉折點。

訂單表設計

sql

-- orders
id, order_code,
platform_id, platform_order_id,
customer_note,
order_status,
order_date, shipped_date,
shipping_cost, packaging_cost,
total_amount, total_amount_jpy,
currency, exchange_rate,
created_at

-- order_items
id, order_id,
item_type, item_id, crafted_item_id,
sale_price, sale_price_jpy,
platform_fee, platform_fee_jpy

訂單生命週期：

created → paid → shipped → completed
                          ↘ cancelled / refunded

paid 觸發庫存狀態變更為 sold；之後的退款與取消以追加事實記錄處理。

任務清單

[ ] 建立 orders + order_items 表 + migration
[ ] sales_records 新增 order_id FK（可選關聯，向後兼容）
[ ] 訂單列表頁 OrderList.vue + 訂單詳情頁 OrderDetail.vue
[ ] ItemDetail / CraftedItemDetail 的「已售」流程改為創建訂單 → 自動關聯 sales_record
[ ] platforms 追加 default_shipping_template JSONB（各地區運費模板）
[ ] 毛利公式升級：毛利 = sale_price_jpy - unit_cost_jpy - platform_fee_jpy - shipping_jpy - packaging_jpy

Phase 0.5.1 — 報關與出貨文件 `⬜ 待開始` `~1-2 週`

目標：在訂單進入 shipped 流程後，從 ERP 直接生成可打印的報關文件與出貨資料。

[ ] 建立報關資料結構與頁面
[ ] 以 docs/COMMERCIAL INVOICE.docx 為基準模板生成報關單
[ ] 從已售商品/訂單提取報關所需資訊
[ ] 與標籤列印流程整合，形成發貨作業閉環

Phase 0.6 — AI 事務輔助層 `⬜ 待開始` `~2 週`

目標：引入受控型 AI，降低人工操作錯誤，保證財務一致性。AI 定位為「輔助執行」而非「自主決策」。

設計約束

AI 不得生成 SQL
AI 不得直接訪問系統外部 API
財務數據必須快照鎖定，不可重算
所有操作寫入 inventory_logs（actor = "AI"）

基礎設施

[ ] AI Gateway（Vercel Function）— 統一 AI 請求入口
[ ] AI Orchestrator — 上下文構建、Tool Router、權限校驗

Tool API

[ ] create_inventory_item — 自然語言創建庫存，自動生成 SKU
[ ] update_listing_status — 狀態流轉帶 AI 校驗
[ ] create_batch — 自動獲取並鎖定月均匯率
[ ] record_sale — 創建訂單 + 銷售記錄，鎖定匯率快照
[ ] get_profit_summary — 只讀財務統計

交互界面

[ ] 聊天式 AI 面板（固定側欄或底部）
[ ] 執行計劃確認彈窗（影響 > 1 條記錄時需確認）
[ ] 操作歷史回顧

Phase 1.0 — Etsy API 集成 `⬜ 待開始` `~3-4 週`

目標：實現 ERP ↔ Etsy 雙向同步，消除手動搬運數據。

重要：Etsy Personal Access 模式（管理自有店鋪，最多 5 間）無需審批，註冊即可使用。

OAuth 2.0 PKCE

Browser → Etsy OAuth (PKCE) → Callback → Supabase (platform_credentials)
                                                ↓
                                   Edge Function (token 自動刷新，有效期 1h)

[ ] 實現 Etsy OAuth 2.0 PKCE 流程
[ ] platform_credentials 表（加密存儲 token）

商品上架同步（ERP → Etsy）

[ ] ItemDetail / CraftedItemDetail 一鍵發布到 Etsy
[ ] listing_id 回寫到 platform_item_id
[ ] 從 ERP 更新 Etsy 價格 / 庫存狀態
[ ] 日文翻譯同步（createListingTranslation, ja）

訂單回拉（Etsy → ERP）

[ ] Edge Function 定時拉取新訂單（getShopReceipts，每 15 min）
[ ] 自動創建 orders 記錄，通過 SKU 匹配庫存
[ ] 訂單狀態同步，發貨信息回寫 Etsy（createReceiptShipment）
[ ] Payment 數據同步（getPayments）— 手續費對賬

市場數據採集

[ ] Edge Function 定期調用 findAllListingsActive（按 taxonomy_id + keywords）
[ ] 存儲 market_price_snapshots：品種 + 重量區間 + 平均價格

Phase 1.5 — 進階數據儀表盤 `⬜ 待開始` `~2 週`

目標：在已有 Dashboard 基礎上，補齊經營分析與可視化能力。

[ ] 月度銷售趨勢、品種分布、產地採購分布圖表
[ ] 訂單數、待發貨數、平台佔比等營運指標
[ ] 按批次 / 品種 / 平台查看毛利、ROI、手續費佔比

Phase 2.0 — 智能定價與自動化 `⬜ 待排期` `~3 週`

目標：從「記錄型」系統進化為「決策輔助型」系統。

[ ] ItemDetail / CraftedItemDetail 顯示市場參考價
[ ] 偏差提醒：標價偏離市場均價 ±20% 時高亮
[ ] AI 定價建議（基於歷史成交 + 市場數據）
[ ] 滯銷提醒：上架超 N 天未售 → 建議降價
[ ] 補貨建議：某品種庫存低於閾值 → 通知
[ ] 訂單發貨提醒：付款後 24h 未標記發貨 → 提醒

時間線

2026-03
├── Phase 0.3    平台主數據 + Lightbox                ✅ 完成
├── Phase 0.3.1  搜索 / 篩選 / 批量操作               ✅ 完成
├── Phase 0.4    標籤打印 + 掃碼                      ✅ 完成
├── Phase 0.4.1  加工品庫存模組                      ✅ 完成
├── Phase 0.4.2  登入系統 + RBAC                     ✅ 完成
├── Phase 0.4.3  Dashboard + 導航重構                ✅ 完成

2026-04+
├── Phase 0.5    訂單模組 + 履約成本                 ⬜ ~2W
├── Phase 0.5.1  報關與出貨文件                      ⬜ ~1-2W
├── Phase 0.6    AI 事務輔助層                        ⬜ ~2W
├── Phase 1.0    Etsy OAuth + 商品 / 訂單同步        ⬜ ~3-4W
├── Phase 1.5    進階數據儀表盤                      ⬜ ~2W
└── Phase 2.0    市場數據 + 智能定價                 ⬜ ~3W

時間估算基於單人開發，可按實際情況調整。

版本標記規劃

版本	對應里程碑	說明
v0.4.x	Phase 0.4.3 完成	已具備原石/加工品庫存、Auth/RBAC、Dashboard、打印掃碼
v0.5.x	Phase 0.5–0.6 完成	內部可用 ERP，具備訂單、履約與 AI 輔助
v1.0	Phase 1.0 完成	接入 Etsy，具備平台聯動能力
v1.5	Phase 1.5 完成	具備數據分析與決策支持
v2.0	Phase 2.0 完成	智能定價，進入決策輔助型系統

技術債（持續推進）

項目	優先級	說明
備份策略	🔴 高	Supabase 自動備份 + 定期導出 CSV
欄位級敏感數據保護	🔴 高	staff 目前僅做前端遮蔽，後續應改為 RPC / 視圖 / 欄位級隔離
CI/CD	🟡 中	GitHub Actions：`vue-tsc` + `pnpm build` + 部署流程
移動端適配	🟡 中	訂單、Dashboard、報關流程需專門適配
E2E 測試	🟢 低	Playwright 關鍵路徑（創建商品、成交、訂單流程）
錯誤監控	🟢 低	Sentry 免費方案或 Supabase Logs
`inventory_items` 瘦身	🟢 低	`sold_price` / `platform_fee` / `sales_platform` 已遷移到 `sales_records`，後續可移除冗餘列
文檔同步機制	🟢 低	`README` 與 roadmap 更新時需同步標記 archive，避免再次堆積過時文檔

附錄 A — Etsy Open API v3 調研

文檔：https://developers.etsy.com/documentation/
認證：OAuth 2.0 PKCE（Personal Access 即時可用，無需審批）
無 Sandbox；無 Webhook（需輪詢）
關鍵端點：createDraftListing / updateListing / uploadListingImage / updateListingInventory / getShopReceipts / createReceiptShipment / getPayments / findAllListingsActive / createListingTranslation

附錄 B — Detonger dtpweb SDK 調研

包名：dtpweb（npm），最新版本 2.7.20251212
架構：Browser → 本地打印助手（HTTP）→ USB 打印機
打印助手：Windows 驅動自帶，零額外部署；v2.7+ 支持 HTTPS 頁面
坐標系：全部 mm，與標籤紙規格直接對應
核心 API：drawText / draw2DQRCode / draw1DBarcode / drawImage / drawTable / drawLine / getPageImage（BASE64 預覽）
歷史參考文檔：docs/archive/printerSDK-README.md

Crystal ERP — 項目計劃 ​

系統概覽 ​

業務模型 ​

SKU：1 SKU = 1 件庫存 ​

銷售渠道：1 SKU → 1 Channel ​

財務：Append-only ​

技術架構 ​

ERP ​

獨立站 ​

系統結構 ​

核心數據表 ​

當前系統能力 ​

開發路線 ​

Phase 0.3 — 體驗完善與平台主數據 ✅ 已完成 ​

Phase 0.3.1 — 搜索、批量操作與平台補齊 ✅ 已完成 ​

Phase 0.4 — 物理連接與標籤打印 ✅ 已完成 ​

Phase 0.4.1 — 加工品庫存模組 ✅ 已完成 ​

Phase 0.4.2 — 登入系統與 RBAC ✅ 已完成 ​

Phase 0.4.3 — Dashboard 與導航重構 ✅ 已完成 ​

Phase 0.5 — 訂單與履約基礎 ⬜ 待開始 ~2 週 ​

訂單表設計 ​

Phase 0.5.1 — 報關與出貨文件 ⬜ 待開始 ~1-2 週 ​

Phase 0.6 — AI 事務輔助層 ⬜ 待開始 ~2 週 ​

Phase 1.0 — Etsy API 集成 ⬜ 待開始 ~3-4 週 ​

OAuth 2.0 PKCE ​

商品上架同步（ERP → Etsy） ​

訂單回拉（Etsy → ERP） ​

市場數據採集 ​

Phase 1.5 — 進階數據儀表盤 ⬜ 待開始 ~2 週 ​

Phase 2.0 — 智能定價與自動化 ⬜ 待排期 ~3 週 ​

時間線 ​

版本標記規劃 ​

技術債（持續推進） ​

附錄 A — Etsy Open API v3 調研 ​

附錄 B — Detonger dtpweb SDK 調研 ​