310 lines
11 KiB
Markdown
310 lines
11 KiB
Markdown
# 多簡訊平台架構設計
|
||
|
||
> 建立日期：2026-06-02
|
||
> 目的：支援 EVERY8D 與三竹（MITAKE）兩個簡訊發送平台
|
||
|
||
---
|
||
|
||
## 需求說明
|
||
|
||
- 加入三竹（MITAKE）簡訊發送平台
|
||
- 整個系統統一切換發送平台（由系統設定決定）
|
||
- 存放帳號參數的 `ProjectMMSAccount` 資料表加入平台代碼欄位
|
||
- 新增 `MMSPlatform` 資料表，存放平台代碼、主帳號密碼等資料（API 端點硬寫於各 Provider 靜態變數）
|
||
- 於 `BWEX` 資料表加入設定 `CurrentMMSPlatform`，記錄目前使用哪一個簡訊平台
|
||
- 簡訊帳號設定畫面需支援：
|
||
- 選擇平台
|
||
- 顯示目前的預設平台
|
||
- 設定各簡訊平台的主帳號密碼
|
||
- 管理各計畫的分帳號密碼
|
||
|
||
---
|
||
|
||
## 架構概覽
|
||
|
||
```
|
||
SMSSendingService.SendMessage()
|
||
└─ switch (message.PlatformCode)
|
||
├─ "EVERY8D" → EVERY8DSMSProvider.SendMMS(...)
|
||
└─ "MITAKE" → MITAKESMSProvider.SendMMS(...)
|
||
```
|
||
|
||
**設計原則：兩個 Provider 均為純靜態類別，不使用介面或工廠，直接 switch 呼叫。**
|
||
|
||
平台代碼優先順序：
|
||
1. `MessageQueueItem.PlatformCode`（由計畫的 `ProjectMMSAccount.PlatformCode` 填入）
|
||
2. 若計畫無設定，使用 `PublicVariable.CurrentMMSPlatform`（由 `BWEX.CurrentMMSPlatform` 載入）
|
||
|
||
---
|
||
|
||
## 資料庫異動
|
||
|
||
### 新增資料表 `MMSPlatform`（簡訊平台設定）
|
||
|
||
| No | Field Name | Data Type | Length | Not Null | PK | Identity | Description |
|
||
| --- | ------------ | --------- | ------ | -------- | --- | -------- | ---------------------- |
|
||
| 1 | ID | INT | | V | V | V | 流水號 |
|
||
| 2 | PlatformCode | NVARCHAR | 20 | V | | | 平台代碼（EVERY8D / MITAKE） |
|
||
| 3 | PlatformName | NVARCHAR | 50 | V | | | 平台名稱（EVERY8D / 三竹） |
|
||
| 4 | Account | NVARCHAR | 100 | | | | 主帳號 |
|
||
| 5 | Password | NVARCHAR | 100 | | | | 主密碼 |
|
||
| 6 | Remark | NVARCHAR | 200 | | | | 備註 |
|
||
| 7 | DB_APPNO | INT | | V | | | 樂觀鎖定版本號 |
|
||
| 8 | DB_CRDAT | DATETIME | | V | | | 建立日期 |
|
||
| 9 | DB_CRUSR | NVARCHAR | 20 | V | | | 建立人員 |
|
||
| 10 | DB_TRDAT | DATETIME | | V | | | 修改日期 |
|
||
| 11 | DB_TRUSR | NVARCHAR | 20 | V | | | 修改人員 |
|
||
|
||
> API 端點網址硬寫於各 Provider 靜態變數，不存入資料庫。
|
||
|
||
預設插入兩筆：
|
||
|
||
| PlatformCode | PlatformName |
|
||
| ------------ | ------------ |
|
||
| EVERY8D | EVERY8D |
|
||
| MITAKE | 三竹 |
|
||
|
||
### 修改資料表 `ProjectMMSAccount`
|
||
|
||
新增欄位：
|
||
|
||
| No | Field Name | Data Type | Length | Not Null | Description |
|
||
| --- | ------------ | --------- | ------ | -------- | ----------- |
|
||
| 5 | PlatformCode | NVARCHAR | 20 | V | 平台代碼 |
|
||
|
||
### 修改資料表 `BWEX`（系統設定）
|
||
|
||
新增一筆設定資料：
|
||
|
||
| KeyName | KeyValue | Description |
|
||
| ------------------ | -------- | ----------- |
|
||
| CurrentMMSPlatform | EVERY8D | 目前使用的簡訊平台代碼 |
|
||
|
||
---
|
||
|
||
## 新增檔案
|
||
|
||
### `Services/MITAKESMSProvider.cs`（三竹靜態類別）
|
||
|
||
- 純靜態類別（`public static class MITAKESMSProvider`）
|
||
- API 端點以靜態變數定義：
|
||
```csharp
|
||
private const string ApiBaseUrl = "https://message.mitake.com.tw";
|
||
```
|
||
- 依 `message.MMSAccount` / `message.MMSPassword` 呼叫三竹 API
|
||
- 三竹 API 端點格式：
|
||
`{ApiBaseUrl}/SmSendGet.asp?username={帳號}&password={密碼}&dstaddr={手機}&smbody={內容}`
|
||
- 回傳格式為純文字：`[1]` 開頭表示成功，`statuscode=` 欄位為狀態碼
|
||
- 三竹狀態碼說明：
|
||
|
||
| statuscode | 說明 |
|
||
| ---------- | ------ |
|
||
| 0 | 已送達手機 |
|
||
| 1 | 已送達三竹 |
|
||
| 2 | 已送達業者 |
|
||
| 1000 | 預約傳送中 |
|
||
| 1001 | 預約已取消 |
|
||
| 2000 | 內容有錯誤 |
|
||
| 2001 | 門號有錯誤 |
|
||
| 2002 | 訊息已停用 |
|
||
| 2003 | 逾時無法送達 |
|
||
| 2005 | 內容有關鍵字 |
|
||
| 2999 | 業者系統錯誤 |
|
||
| 9998 | 傳送錯誤 |
|
||
| 9999 | 三竹系統錯誤 |
|
||
|
||
|
||
- `CheckBalance`：呼叫 `{ApiBaseUrl}/SmQueryGet.asp?username={帳號}&password={密碼}&CharsetURL=UTF-8`
|
||
|
||
### `Models/MMSPlatformItem.cs`（資料紀錄類別）
|
||
|
||
對應 `MMSPlatform` 資料表的單筆資料，屬性包含：
|
||
`ID`、`PlatformCode`、`PlatformName`、`Account`、`Password`、`Remark`，以及標準 DB 欄位。
|
||
|
||
### `Models/MMSPlatformList.cs`（資料集合類別）
|
||
|
||
`List<MMSPlatformItem>` 的集合類別。
|
||
|
||
### `DAC/DAC_MMSPlatform.cs`（資料存取類別）
|
||
|
||
- `MMSPlatformList SelectAll()` — 查詢所有平台
|
||
- `MMSPlatformItem SelectByCode(string platformCode)` — 依代碼查一筆
|
||
- `MMSPlatformItem InsertOne(MMSPlatformItem item)` — 新增
|
||
- `MMSPlatformItem UpdateOne(MMSPlatformItem item)` — 修改（含 `DB_APPNO` 樂觀鎖定）
|
||
|
||
---
|
||
|
||
## 修改現有檔案
|
||
|
||
### `Services/EVERY8DSMSProvider.cs`
|
||
|
||
- 維持純靜態類別，不需異動介面或繼承關係
|
||
- `SendMMS`、`CheckBalance` 保持 static 方法不變
|
||
- API 端點以靜態常數定義（已存在或補充確認）：
|
||
```csharp
|
||
private const string ApiBaseUrl = "https://new.e8d.tw/API21/HTTP";
|
||
```
|
||
|
||
### `Models/ProjectMMSAccountItem.cs`（或所在類別檔）
|
||
|
||
新增屬性：
|
||
```csharp
|
||
public string PlatformCode { get; set; }
|
||
```
|
||
|
||
### `Models/MessageQueueItem.cs`（或所在類別檔）
|
||
|
||
新增屬性：
|
||
```csharp
|
||
public string PlatformCode { get; set; }
|
||
```
|
||
|
||
### `DAC/DAC_ProjectMMSAccount.cs`
|
||
|
||
- `SelectPage`、`Select`、`InsertOne`、`UpdateOne` 均加入 `PlatformCode` 欄位處理
|
||
|
||
### `Common/PublicVariable.cs`
|
||
|
||
新增靜態變數：
|
||
```csharp
|
||
/// <summary>
|
||
/// 目前使用的簡訊平台代碼（由 BWEX.CurrentMMSPlatform 載入）
|
||
/// </summary>
|
||
public static string CurrentMMSPlatform = "EVERY8D";
|
||
```
|
||
|
||
### `Global.asax.cs`
|
||
|
||
`Application_Start` 新增從 DB 讀取 `BWEX` 的 `CurrentMMSPlatform`，設定至 `PublicVariable.CurrentMMSPlatform`。
|
||
EVERY8D 相關的 AppSettings 讀取保留作為向後相容 fallback。
|
||
|
||
### `Services/SMSSendingService.cs`
|
||
|
||
- `Start()` 的帳號填入迴圈，同時填入 `message.PlatformCode`：
|
||
- 計畫有設定 `PlatformCode` → 使用計畫的 `PlatformCode`
|
||
- 否則使用 `PublicVariable.CurrentMMSPlatform`
|
||
- `SendMessage()` 改用 `switch (message.PlatformCode)` 直接呼叫對應靜態 Provider，移除 `SendSMSToEVERY8D()` 方法：
|
||
|
||
```csharp
|
||
switch (message.PlatformCode)
|
||
{
|
||
case "MITAKE":
|
||
result = MITAKESMSProvider.SendMMS(message, out failMessage);
|
||
break;
|
||
default: // EVERY8D
|
||
result = EVERY8DSMSProvider.SendMMS(message, out failMessage);
|
||
break;
|
||
}
|
||
```
|
||
|
||
### `Services/MessageAccountManage.asmx.cs`
|
||
|
||
新增 WebMethod：
|
||
|
||
| Method | 說明 |
|
||
| ----------------------------------------- | ------------------------------------------------- |
|
||
| `GetPlatforms()` | 回傳所有平台清單（BaseResponse, Data: MMSPlatformList） |
|
||
| `GetCurrentPlatform()` | 回傳目前系統預設平台代碼（BaseResponse, Data: MMSPlatformItem） |
|
||
| `SavePlatform(MMSPlatformItem item)` | 儲存平台設定（帳號 / 密碼） |
|
||
| `SetCurrentPlatform(string platformCode)` | 更新 BWEX 的 CurrentMMSPlatform，同時更新 PublicVariable |
|
||
|
||
修改 `Save()`：加入 `PlatformCode` 欄位的驗證與儲存。
|
||
|
||
### `Forms/MessageAccountManage.aspx`
|
||
|
||
畫面新增區塊：
|
||
|
||
1. **目前預設平台區塊**（搜尋面板上方）：
|
||
- 顯示目前使用的平台名稱與代碼
|
||
- 提供「切換平台」按鈕開啟平台切換彈窗
|
||
|
||
2. **平台設定區塊**（可展開/收合）：
|
||
- 列出所有平台（EVERY8D、三竹）
|
||
- 每平台顯示：主帳號、主密碼、操作按鈕（儲存）（API 端點固定於程式碼，不顯示於畫面）
|
||
|
||
3. **列表欄位**：
|
||
- 新增「平台」欄（顯示 `PlatformCode`，NULL 時顯示「系統預設」）
|
||
|
||
4. **新增/編輯彈窗**：
|
||
- 新增「使用平台」下拉選單（選項：`使用系統預設`、`EVERY8D`、`三竹`）
|
||
|
||
### `Scripts/MessageAccountManage.js`
|
||
|
||
新增 `data`：
|
||
- `platforms: []` — 平台清單
|
||
- `currentPlatform: null` — 目前預設平台物件
|
||
- `showPlatformSettings: false` — 控制平台設定展開
|
||
- `showSwitchModal: false` — 切換平台彈窗
|
||
|
||
新增 `methods`：
|
||
- `loadPlatforms()` — 呼叫 `GetPlatforms()`
|
||
- `loadCurrentPlatform()` — 呼叫 `GetCurrentPlatform()`
|
||
- `savePlatformSetting(platform)` — 呼叫 `SavePlatform()`
|
||
- `setCurrentPlatform(platformCode)` — 呼叫 `SetCurrentPlatform()`
|
||
|
||
修改 `editItem`：
|
||
- 新增 `PlatformCode: ''`（空字串 = 使用系統預設）
|
||
|
||
---
|
||
|
||
## 三竹 API 說明
|
||
|
||
### 發送 API
|
||
|
||
```
|
||
ApiBaseUrl = https://message.mitake.com.tw (硬寫於 MITAKESMSProvider)
|
||
|
||
GET/POST {ApiBaseUrl}/SmSendGet.asp
|
||
參數：
|
||
username = 帳號
|
||
password = 密碼
|
||
dstaddr = 手機號碼（多筆以 $ 分隔）
|
||
smbody = 簡訊內容（URL Encode, UTF-8）
|
||
CharsetURL = UTF-8
|
||
```
|
||
|
||
回傳格式（純文字，每筆一行）：
|
||
```
|
||
[序號]
|
||
statuscode=1
|
||
destaddr=0912345678
|
||
msgid=訊息ID
|
||
```
|
||
|
||
### 查詢餘額 API
|
||
|
||
```
|
||
GET {ApiBaseUrl}/SmQueryGet.asp
|
||
參數：
|
||
username = 帳號
|
||
password = 密碼
|
||
CharsetURL = UTF-8
|
||
```
|
||
|
||
回傳格式：
|
||
```
|
||
AccountPoint=100
|
||
```
|
||
|
||
---
|
||
|
||
## 檔案清單
|
||
|
||
| 異動類型 | 路徑 |
|
||
| ---- | --------------------------------------- |
|
||
| 新增 | `DOC/多簡訊平台架構設計.md` |
|
||
| 新增 | `Services/MITAKESMSProvider.cs` |
|
||
| 新增 | `Models/MMSPlatformItem.cs` |
|
||
| 新增 | `Models/MMSPlatformList.cs` |
|
||
| 新增 | `DAC/DAC_MMSPlatform.cs` |
|
||
| 修改 | `Services/EVERY8DSMSProvider.cs` |
|
||
| 修改 | `Models/ProjectMMSAccountItem.cs` |
|
||
| 修改 | `Models/MessageQueueItem.cs` |
|
||
| 修改 | `DAC/DAC_ProjectMMSAccount.cs` |
|
||
| 修改 | `Common/PublicVariable.cs` |
|
||
| 修改 | `Global.asax.cs` |
|
||
| 修改 | `Services/SMSSendingService.cs` |
|
||
| 修改 | `Services/MessageAccountManage.asmx.cs` |
|
||
| 修改 | `Forms/MessageAccountManage.aspx` |
|
||
| 修改 | `Scripts/MessageAccountManage.js` |
|