EasyLink 系統架構藍圖 v3.0

📋 執行摘要

EasyLink 是一個三層級 SaaS 支付平台，支持 平台方 (超級管理員) → 代理商 → 商戶的業務模式。

                核心功能:
                多租戶架構，數據完全隔離
代理商管理系統，支持角色權限控制
商戶入網工作流程，含審批機制
WhatsApp 通知集成 (CloudWAPI)
EasyLink 支付網關集成 (預留接口)

            

🏗️ 系統架構

層級圖

第一層

超級管理員

平台管理

→

第二層

代理商門戶

商戶管理

→

第三層

商戶客戶端

支付處理

→

第四層

EasyLink API

支付網關

技術棧

前端

HTML5 + CSS3 (原生)
Cloudflare Pages (託管)
自定義域名 SSL

後端

Cloudflare Workers
D1 數據庫 (SQLite)
RESTful API

第三方集成

CloudWAPI (WhatsApp)
EasyLink 支付
Cloudflare R2 (文件存儲)

🌐 域名結構

域名	用途	Pages 項目	狀態
upay-saas.jkdcoding.com	超級管理員控制台	easylink-saas	✅ 運行中
upay-agent.jkdcoding.com	代理商登入門戶	easylink-agent-portal	✅ 運行中
upay-newapp.jkdcoding.com	商戶入網表單	easylink-agent-portal	✅ 運行中
king-chicken.jkdcoding.com	KC 商戶客戶端	easylink-client-kingchicken	✅ 運行中
easylink-api-v2.jimsbond007.workers.dev	API Worker	N/A (Worker)	✅ 運行中

📁 目錄結構

easylink/
│
├── 📁 agent-portal/                    # 主平台文件
│   ├── index.html                      # 代理商控制台
│   ├── platform-overview.html          # 平台說明文件
│   ├── login.html                      # 代理商登入
│   ├── new-application.html            # 商戶申請表單
│   ├── api-client.js                   # API 客戶端庫
│   └── _redirects                      # 域名路由規則
│
├── 📁 deploy-login/                    # 獨立項目: 代理商登入
│   ├── index.html                      # 生產登入頁面
│   └── api-client.js                   # API 客戶端
│
├── 📁 deploy-newapp/                   # 獨立項目: 商戶申請
│   ├── index.html                      # 申請表單
│   └── api-client.js                   # API 客戶端
│
├── 📁 clients/kingchicken/             # KC 商戶客戶端
│   ├── index.html                      # 支付頁面
│   ├── login.html                      # 商戶登入
│   ├── admin.html                      # 交易記錄
│   ├── boss-report.html                # 管理員 WhatsApp 報告
│   ├── drivers.html                    # 渠道管理
│   └── ...
│
├── 📁 easylink-infra/worker/           # 後端 API
│   ├── src/
│   │   └── index.js                    # Worker 主代碼
│   ├── wrangler.toml                   # Worker 配置
│   └── schema-v3.0.sql                 # 數據庫結構
│
├── 📁 docs/                            # 文檔
│   ├── SYSTEM_ARCHITECTURE_DESIGN.md   # 詳細架構設計
│   ├── CHANGE_LOG_v3.0.md              # 變更日誌
│   └── ...
│
├── 📁 .github/workflows/               # CI/CD
│   └── deploy-all.yml                  # 自動部署
│
├── 📁 super-admin/                     # 超級管理控制台
│   ├── index.html                      # 管理主頁
│   ├── admin-dashboard.html            # 系統儀表板
│   ├── system-blueprint.html           # 本文件
│   └── platform-overview.html          # 平台說明
│
└── system-blueprint.html               # 📍 本文件

                ⚠️ 重要提示: deploy-login/ 和 deploy-newapp/ 是
                獨立的單獨項目，部署到不同的 Pages 項目。
                它們不屬於主 agent-portal/ 文件夾。
            

🔌 API 端點

認證

端點	方法	描述	權限
`/api/v1/auth/agent/login`	POST	代理商登入 (名稱 + 密碼)	公開
`/api/v1/auth/agent/register`	POST	創建新代理商 (僅超級管理員)	管理員
`/api/v1/admin/agents`	GET	列出所有代理商	管理員

商戶申請

端點	方法	描述	權限
`/api/v1/agent/applications`	POST	提交新申請	代理商
`/api/v1/agent/applications`	GET	列出申請 (自己的/全部)	代理商/管理員
`/api/v1/admin/applications/review`	POST	審核申請	管理員

Webhook (預留)

端點	方法	描述
`/webhooks/easylink/merchant-approved`	POST	EasyLink 審核回調

🗄️ 數據庫結構 (v3.0)

核心數據表

agents (代理商)

代理商賬戶和憑證

agent_id (主鍵)
agent_name (唯一)
whatsapp (唯一)
role (admin/viewer)

merchant_applications (商戶申請)

商戶入網申請

app_id (主鍵)
agent_id (外鍵)
status (狀態)
easylink_* 字段

notifications (通知)

WhatsApp 通知日誌

id (主鍵)
recipient_phone
message_content
cloudwapi_response

完整結構: 參見 easylink-infra/worker/schema-v3.0.sql

🔄 商戶入網工作流程

1

代理商
提交申請

→

2

WhatsApp
通知

→

3

超級管理員
審核

→

4

發送至
EasyLink

→

5

自動創建
賬戶

狀態流程

pending_review (待審核) → approved (已批准) → sent_to_easylink (已發送) → completed (已完成)
                      ↘ rejected (已拒絕)
                      ↘ need_info (需補充資料) → pending_review (待審核)

🔒 安全說明

                ⚠️ 關鍵規則:
                WhatsApp 號碼: 使用 852XXXXXXXX 格式 (不加 "+" 前綴)
超級管理員憑證: jkdcoding / brucelee
代理商密碼: 當前為明文存儲 (生產環境應加密)
令牌: 代理商令牌 8 小時過期

            

角色權限

角色	創建代理商	提交申請	審核	查看數據
超級管理員	✅ 全部	❌ 否	✅ 全部	✅ 全部
代理商管理員	❌ 否	✅ 自己的	❌ 否	✅ 自己的商戶
代理商檢視員	❌ 否	❌ 否	❌ 否	✅ 自己的商戶 (只讀)

⚙️ CI/CD 自動化

GitHub Actions 工作流

文件: .github/workflows/deploy-all.yml

                觸發條件:
                推送到 main 或 master 分支
手動觸發 (workflow_dispatch)

            

部署順序

部署 Worker API (easylink-api-v2)
部署代理門戶 (upay-saas.jkdcoding.com)
部署代理登入 (upay-agent.jkdcoding.com)
部署商戶申請 (upay-newapp.jkdcoding.com)
部署 KC 客戶端 (king-chicken.jkdcoding.com)

所需密鑰

密鑰名稱	描述
`CLOUDFLARE_API_TOKEN`	API 訪問超級令牌
`CLOUDFLARE_ACCOUNT_ID`	賬戶 ID: dfbee5c2a5706a81bc04675499c933d4

🛠️ 維護指南

添加新代理商

登入 upay-saas.jkdcoding.com 作為超級管理員
點擊 🔐 按並驗證 (jkdcoding/brucelee)
填寫代理商表單: 名稱、WhatsApp (852XXXXXXXX)、郵箱 (可選)、角色
系統自動生成臨時密碼
複製憑證並通過 WhatsApp 發送給代理商

手動部署 (如 CI/CD 失敗)

# 部署 Worker
cd easylink-infra/worker
wrangler deploy --env=production

# 部署代理門戶
cd agent-portal
wrangler pages deploy . --project-name=easylink-agent-portal

# 部署代理登入
cd deploy-login
wrangler pages deploy . --project-name=easylink-agent-login

# 部署商戶申請
cd deploy-newapp
wrangler pages deploy . --project-name=easylink-agent-newapp

數據庫遷移

# 執行結構更新
wrangler d1 execute easylink-db-v2 --file=schema-v3.0.sql --remote

🐛 故障排除

DNS 無法解析

檢查 Cloudflare DNS 中的 CNAME 記錄:

upay-agent → easylink-agent-portal.pages.dev
upay-newapp → easylink-agent-portal.pages.dev

API 401 錯誤

檢查令牌過期:

代理商令牌 8 小時過期
超級管理員使用靜態憑證

WhatsApp 無法發送

檢查 CloudWAPI:

驗證手機格式 (852XXXXXXXX)
檢查 CloudWAPI 餘額

📞 聯繫與支持

系統架構師	母機團隊 (Mother Machine Team)
代碼倉庫	github.com/twmeric/easylink-agent-portal
超級管理員	jkdcoding / brucelee
WhatsApp 通知	85251164453