🇲🇾 YiJian ERP System

針對馬來西亞中小企業的現代化 ERP 系統，整合 LHDN e-Invoice (MyInvois API)，支援多行業稅務配置和 SST 自動計算。

---

📋 目錄

• 產品概述
• 核心功能
• 專案結構
• 技術架構
• 開發環境設置
• 部署指南
• 相關文檔

---

🎯 產品概述

產品定位

本系統是一個完整的企業資源規劃 (ERP) 系統，專為馬來西亞市場設計，核心特色：

• e-Invoice 整合: 完全符合 LHDN MyInvois API 規範
• 多行業支援: 15+ 行業預設配置 (零售、餐飲、專業服務等)
• SST 自動化: 智能稅率計算引擎，支援 Sales Tax 和 Service Tax
• 桌面應用交付: 通過 Electron 打包，提供原生桌面體驗

專案生態

┌─────────────────────────────────────────────────────────────────┐
│                         專案生態系統                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ERP-System (本專案)          ERP-Admin-Portal                 │
│   ├── apps/web                 內部管理後台                      │
│   ├── apps/api        ◄───────  - 用戶管理                      │
│   ├── apps/desktop             - 訂閱管理                       │
│   └── apps/ai-service          - 數據分析                       │
│                                                                 │
│   ERP-Official-Website                                          │
│   產品官網                                                       │
│   - 產品介紹                                                     │
│   - 註冊引導                                                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

✨ 核心功能

標準 ERP 模組

模組	說明
產品管理	SKU、分類、定價、庫存追蹤
客戶管理	客戶資料、信用額度、交易歷史
供應商管理	供應商資料、採購價格、交貨期
訂單管理	銷售訂單、採購訂單、訂單履行
發票管理	發票建立、列印、付款追蹤
倉庫管理	多倉庫、庫存調撥、批號追蹤
報表分析	銷售報表、庫存報表、財務摘要

e-Invoice 整合 (LHDN MyInvois)

功能	說明
分類代碼	完整 45 個 LHDN 分類代碼支援
MSIC 代碼	馬來西亞標準工業分類代碼
稅率引擎	自動判斷 SST 適用稅率
API 提交	直接提交至 MyInvois API
QR 驗證	驗證後自動生成 QR Code

AI 功能 (可選)

功能	說明
需求預測	基於歷史數據的智能預測
庫存優化	自動再訂購點建議
AI 助手	自然語言查詢 (Enterprise)

---

📁 專案結構

erp-system/
├── apps/
│   ├── web/                 # React 前端 (Vite)
│   │   ├── src/
│   │   │   ├── components/  # UI 組件
│   │   │   ├── routes/      # TanStack Router 頁面
│   │   │   ├── stores/      # Zustand 狀態管理
│   │   │   ├── lib/         # 工具函數和 API 客戶端
│   │   │   └── mocks/       # MSW Mock 數據
│   │   └── package.json
│   │
│   ├── api/                 # Fastify 後端
│   │   ├── src/
│   │   │   ├── routes/      # API 路由
│   │   │   ├── middleware/  # 認證、授權中間件
│   │   │   └── lib/         # 工具函數
│   │   └── package.json
│   │
│   ├── desktop/             # Electron 桌面應用
│   │   ├── src/
│   │   │   ├── main/        # 主進程
│   │   │   └── preload/     # 預載腳本
│   │   └── package.json
│   │
│   └── ai-service/          # Python AI 服務
│       ├── app/
│       └── requirements.txt
│
├── packages/
│   ├── database/            # Prisma ORM
│   ├── shared-types/        # 共享 TypeScript 類型
│   ├── config/              # 共享配置
│   └── logger/              # 日誌模組
│
├── docs/                    # 文檔
│   └── cloudflare-tunnel-setup.md
│
└── 規劃文檔/
    ├── 00-INDEX.md          # 文檔索引
    ├── 01-INDUSTRY-CONFIG.md # 行業配置
    ├── 02-TAX-RATES.md      # 稅率規範
    ├── 03-CLASSIFICATION.md # 分類代碼
    ├── 04-MSIC-CODES.md     # MSIC 代碼
    ├── 05-TAX-ENGINE.md     # 稅率引擎
    └── 06-INVOICE-PRINT-TEMPLATE.md # 發票模板

---

🛠️ 技術架構

前端

技術	用途
React 18	UI 框架
TypeScript	類型安全
Vite	建構工具
TanStack Router	路由
TanStack Query	服務端狀態
Zustand	客戶端狀態
Tailwind CSS	樣式
shadcn/ui	UI 組件庫
Framer Motion	動畫

後端

技術	用途
Node.js 20+	運行環境
Fastify	Web 框架
Prisma	ORM
PostgreSQL	數據庫
Redis	緩存和會話
Zod	驗證

桌面應用

技術	用途
Electron	桌面運行時
electron-builder	打包
contextBridge	安全 IPC

---

🚀 開發環境設置

前置需求

軟體	版本
Node.js	≥ 20.0.0
pnpm	≥ 9.0.0
Docker	Latest
Git	Latest

快速開始

# 1. 克隆專案
git clone <repository-url>
cd erp-system

# 2. 安裝依賴
pnpm install

# 3. 啟動基礎服務 (PostgreSQL, Redis)
docker-compose up -d postgres redis

# 4. 配置環境變量
cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env

# 5. 初始化數據庫
pnpm db:generate
pnpm db:push
pnpm db:seed

# 6. 啟動開發服務器
pnpm dev

開發服務器：

• 前端: http://localhost:5173
• 後端 API: http://localhost:3000

桌面應用開發

# 開發模式
pnpm desktop:dev

# 打包
pnpm desktop:build
pnpm desktop:package:win

---

🏭 部署指南

後端部署 (NAS)

後端 API 部署在 Synology NAS 上：

1. 開發階段: 使用 Tailscale VPN 連接
2. 生產階段: 使用 Cloudflare Tunnel

詳細設置請參考: Cloudflare Tunnel 設置指南

桌面應用分發

# 生產建構
pnpm desktop:build:production

# 打包為安裝程式
pnpm desktop:package:win   # Windows
pnpm desktop:package:mac   # macOS
pnpm desktop:package:linux # Linux

---

📚 相關文檔

規劃文檔

文檔	說明
00-INDEX.md	文檔索引和架構總覽
01-INDUSTRY-CONFIG.md	商業領域配置
02-TAX-RATES.md	SST 稅率規範
03-CLASSIFICATION.md	LHDN 分類代碼
04-MSIC-CODES.md	MSIC 代碼
05-TAX-ENGINE.md	稅率自動化引擎
06-INVOICE-PRINT-TEMPLATE.md	發票列印模板

技術文檔

文檔	說明
E-Invoice.md	MyInvois API 整合規範
DEPLOYMENT_GUIDE.md	部署指南
docs/cloudflare-tunnel-setup.md	Cloudflare Tunnel 設置

---

📜 開發規範

本專案遵循以下開發規範，詳見 .agent/rules/:

• rules.md: Desktop-First 開發流程、API 整合規範
• security.md: 企業安全標準
• frontend-design.md: Modern Clean SaaS 設計規範

---

📄 授權

Proprietary - 版權所有

---

最後更新: 2025-12-27