EasyLink 支付平台 - 項目總覽與操作手冊

🌐 域名用途區分

upay-saas.jkdcoding.com

你現在的位置 — 這是統一項目文檔與架構總覽站。適合開發者、AI 助手、新加入的團隊成員快速了解全局。

upay-agent.jkdcoding.com

代理商控制台 — 這是代理商日常使用的 Dashboard、提交商戶申請、查看業績的實際工作入口。

AI 提示：當需要查閱項目背景、架構、待辦清單時，請引用 upay-saas.jkdcoding.com；當需要執行代理商業務流程（登入、提交申請、審核）時，請引用 upay-agent.jkdcoding.com。

🎯 項目概述

AI 提示：這是一個基於 Cloudflare Workers + Pages + D1 + R2 構建的三級 SaaS 支付平台。核心設計原則是：一個 Worker 服務所有商戶，數據在 D1 層通過 tenant_id 隔離，每個商戶擁有獨立部署的 Pages 前端。

EasyLink 採用 平台方 (Super Admin) → 代理商 (Agent) → 商戶 (Merchant) 的三級架構。代理商通過 Agent Portal 提交新商戶入網申請，Super Admin 審核後開通獨立商戶系統。

🌐 前端託管

Cloudflare Pages（多個獨立項目）

⚡ 後端 API

Cloudflare Workers (easylink-api-v2)

🗄️ 數據庫

Cloudflare D1 (SQLite)

📎 文件存儲

Cloudflare R2 (easylink-files)

🔗 快速鏈接與測試憑證

🎛️ 系統入口

Agent Portal 主站

代理商控制台（含 Dashboard、申請列表、資料庫）

https://upay-agent.jkdcoding.com

備用: https://easylink-agent-portal.pages.dev

Agent 獨立登入頁

代理商專用登入入口（暫無獨立自定義域名）

https://easylink-agent-login.pages.dev

商戶入網申請表單

5步驟表單，支持文件上傳（商業登記證、身份證、現場照片等）

https://upay-newapp.jkdcoding.com

備用: https://easylink-agent-newapp.pages.dev

Super Admin 後台

審核商戶申請、管理代理商、查看系統狀態（暫無自定義域名）

https://easylink-super-admin.pages.dev

API Worker 健康檢查

後端狀態監控端點（Worker 暫無自定義域名）

https://easylink-api-v2.jimsbond007.workers.dev/health

🔐 測試憑證（已統一）

注意：以下憑證僅供測試與開發使用，生產環境務必修改。

角色	帳號	密碼	入口
Super Admin	`admin`	`admin360`	Super Admin 後台
Agent (代理商)	`admin`	`admin360`	Agent Portal / 獨立登入頁

🏗️ 業務流程與架構

商戶入網申請流程

Agent
填寫表單
上傳文件

→

Worker
存入 D1
文件入 R2

→

WhatsApp
通知 Admin
待審核

→

Super Admin
查看文件
批准/拒絕

→

開通商戶
生成賬號
WhatsApp 通知

系統分層架構

Layer 1: Super Admin (平台管理員)
  └─ 管理所有代理商和商戶
  └─ 審核商戶入網申請

Layer 2: Agent Portal (代理商)
  └─ 查看旗下商戶與業績
  └─ 提交新商戶入網申請
  └─ 佣金收入統計

Layer 3: Merchant Client (商戶)
  └─ 獨立 Pages 項目 + 獨立域名
  └─ 支付頁面 / 管理後台 / 渠道管理 / WhatsApp 日報

Layer 4: Backend Infrastructure
  └─ Cloudflare Worker (統一 API)
  └─ Cloudflare D1 (多租戶數據隔離)
  └─ Cloudflare R2 (申請文件存儲)
  └─ CloudWAPI (WhatsApp 通知)

📁 本地項目結構

AI 提示：項目根目錄為 E:\Projects\Easylink。請勿再參照舊路徑 C:\Users\Owner\Cloudflare\Easylink（已刪除）。

E:\Projects\Easylink
├── agent-portal/              # 代理商主門戶 (Pages: easylink-agent-portal)
│   ├── index.html
│   ├── login.html
│   ├── new-application.html   # 已重寫，支持真實文件上傳
│   ├── platform-overview.html # 本文件 (upay-saas 落地頁)
│   └── api-client.js          # 已修正端點與認證
│
├── deploy-login/              # 獨立登入頁 (Pages: easylink-agent-login)
├── deploy-newapp/             # 獨立申請表單 (Pages: easylink-agent-newapp)
├── super-admin/               # 超管後台 (Pages: easylink-super-admin)
│   ├── index.html
│   ├── applications.html      # 審核申請 + 查看文件
│   ├── agents.html
│   └── system-blueprint.html
│
├── templates/                 # 商戶模板
│   ├── merchant-template/     # 標準模板
│   └── _dummy/                # 測試商戶 (待部署驗證)
│
├── easylink-infra/            # 後端基礎設施
│   ├── worker/
│   │   ├── src/index.js       # 統一 API Worker (v4.1，已支持文件上傳)
│   │   └── wrangler.toml      # 已綁定 R2 bucket: easylink-files
│   └── database/              # D1 Schema 與遷移腳本
│
├── docs/                      # 項目文檔 (MD)
├── scripts/                   # 部署腳本
├── .github/workflows/         # CI/CD
├── .archive/                  # 歸檔文件
├── README.md
├── PROJECT_STRUCTURE.md       # 已重寫
└── system-blueprint.html      # 根目錄架構圖文檔

🔌 核心 API 端點

Base URL: https://easylink-api-v2.jimsbond007.workers.dev

認證

Endpoint	Method	Auth	說明
`/api/v1/auth/agent/login`	POST	Public	Agent 登入 (agent_name + password)
`/api/v1/auth/agent/register`	POST	Admin	創建 Agent (Super Admin 專用)
`/api/v1/auth/verify`	GET	Bearer	驗證 Token 有效性

Agent 應用

Endpoint	Method	Auth	說明
`/api/v1/agent/dashboard`	GET	Agent	Dashboard 統計數據
`/api/v1/agent/merchants`	GET	Agent	旗下商戶列表
`/api/v1/agent/applications`	POST	Agent	提交商戶申請 (支持 FormData 文件)
`/api/v1/agent/applications`	GET	Agent/Admin	申請列表
`/api/v1/agent/applications/:id`	GET	Agent/Admin	申請詳情
`/api/v1/agent/applications/draft`	POST	Agent	保存草稿

Super Admin 審核

Endpoint	Method	Auth	說明
`/api/v1/admin/agents`	GET	Admin	所有代理商列表
`/api/v1/admin/applications/review`	POST	Admin	審核申請 (approve/reject/need_info)

文件服務

Endpoint	說明
`/files/applications/{app_id}/{filename}`	下載申請上傳的文件 (R2 代理)

🚀 部署狀態

服務	Pages/Worker 名稱	狀態	網址
Worker API	easylink-api-v2	✅ Active v4.1	easylink-api-v2.jimsbond007.workers.dev
Agent Portal	easylink-agent-portal	✅ Active	upay-agent.jkdcoding.com easylink-agent-portal.pages.dev
Agent Login	easylink-agent-login	✅ Active	easylink-agent-login.pages.dev
New Application	easylink-agent-newapp	✅ Active	upay-newapp.jkdcoding.com easylink-agent-newapp.pages.dev
Super Admin	easylink-super-admin	✅ Active	easylink-super-admin.pages.dev
KC Merchant	easylink-client-kingchicken	✅ Active	king-chicken.jkdcoding.com easylink-client-kingchicken.pages.dev
Dummy Template	easylink-client-dummy	❌ Not Deployed	-

⚠️ 待開發 / 未完成清單

AI 提示：以下任務按優先級排列。若用戶詢問「還有什麼要做」，請優先提及高優先級項。

🔴 高優先級（影響核心流程）

☑️ 1. EasyLink 官方 API 自動對接
已完成。Admin 點「批准」後，Worker 會自動調用 /openApi/merchant/register 提交商戶資料；成功後狀態變為 sent_to_easylink，並自動創建 tenant 與 WhatsApp 通知 Agent。

☑️ 2. 生產數據庫憑證同步
已完成。生產 D1 的 admin_users 與 agents 已統一為 admin / admin360；舊測試帳號已清理。

3. 自定義域名 DNS 配置
部分完成。Agent Portal (upay-agent)、申請表單 (upay-newapp)、SaaS 文檔 (upay-saas) 和 KC 商戶 (king-chicken) 的自定義域名已生效。
仍待配置： Agent 獨立登入頁、Super Admin 後台尚未擁有專屬自定義域名。

🟡 中優先級（影響運營效率）

☑️ 4. Agent Dashboard 交易額統計
已完成。tenants 表已新增 agent_id，現有商戶已關聯至 AG001；Agent Dashboard 與 Merchants API 現可正確返回交易統計。

☑️ 5. _dummy 測試商戶部署驗證
已完成。templates/_dummy/ 已成功部署至 easylink-client-dummy，線上地址為 https://7a184179.easylink-client-dummy.pages.dev。

6. 密碼哈希化
當前 Admin 和 Agent 密碼均以明文存儲。生產環境需改用 bcrypt 或 scrypt 哈希。

☑️ 7. King Chicken 商戶源碼歸檔整理
已完成。KC 商戶源碼已從已部署站點恢復並歸檔至 E:\Projects\Easylink\clients\kingchicken\，包含完整配置文件與說明文檔。

🟢 低優先級（增強體驗）

8. 一鍵開通腳本
開發自動化腳本：輸入商戶信息 → 複製模板 → 修改 config.js → 部署 Pages → 創建 tenant → 通知 Agent。

9. 多語言支持
目前僅支持繁體中文，未來可擴展簡體中文 / English。

10. 數據報表導出
Admin 和 Agent 後台增加 CSV / Excel 導出功能。

🛠️ 維護與故障排查

重新部署 Worker

cd easylink-infra/worker
wrangler deploy

部署所有前端

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

cd ../super-admin
wrangler pages deploy . --project-name=easylink-super-admin

更新生產數據庫憑證

wrangler d1 execute payment-db --remote --command="UPDATE admin_users SET email='admin', password='admin360' WHERE email='jkdcoding';"
wrangler d1 execute payment-db --remote --command="UPDATE agents SET agent_name='admin', password_hash='admin360' WHERE agent_name='張代理';"

常見問題：WhatsApp 發送失敗

1. 檢查手機號格式是否為 852XXXXXXXX（不含 +）
2. 檢查 CloudWAPI 餘額
3. 檢查 Worker 日誌中的 [WhatsApp] Send error