活動、洗碼
============

[TOC]

## 系統架構

以舊皇為核心，整合異質技術子系統`.NET` + `PHP` + `Java` + `NodeJS` ...互相以API聯繫擴充，構成系統的子系統群。

erDiagram

H1 ||--|| External : ext
H1 ||--|| Internal : int
External ||--o{ Finance : external
External ||--|{ Campaign : external
Internal ||--|{ Member : internal
Internal ||--|{ Report : internal
Internal ||--|{ GameProvider : internal

H1 {
  subsys Hierarchy
  subsys Member
  subsys GameProvider
  api Campaign
  api Finance
}
Member {
  member Player
  member Agent
  member Affiliate
}
Campaign {
  subsys Campaign
  subsys Rolling
}
Finance{
  api Deposit
  api Withdraw
}
Report{
  service Finance
  service Winlose
  service Commission
}
GameProvider{
  service W1
  service RG

}

## 活動流程

前提
活動種類分為先贈分、後贈分
不能同時參加活動，減少套利風險。

規則
1. 流水型
> 活動期間的流水達到門檻為通過
2. 過招型
> 活動餘額達到門檻即為通過

主動參舉型
被動參與型
> 充值 n 倍碼量

後贈分用途為:
> 1. 舊帶新，推薦人需達成 n位下線達成門檻後才贈
> 2. 抽獎券
> 3. 隔日贈 (返水、隔日 隔週 隔月)
> api 要加贈金類 不用算rolling，舊帶新類
> 4. 龍虎榜 (日榜 週榜(7個日榜最高) 月榜(日冠次數最多，必滿28天，平手平分獎金)) H1可能因匯總帳無法抓出最高分
> 5. 累積贏分榜

先贈分用途為:
> 1. 註冊贈
> 2. 首儲贈
> 3. 全平台、特定種類、特定遊戲的流水、贏分、輸分

通過門檻:
> 1. 活動點數(報名點 + 活動點)歸零
> 2. 達成指定目標

重點事項
會員儲值被動參加充值過流水
1. 會員能參加幾次，有上限，無上限 (例，一天參加一次 最多參加五次)
2. 參加前需要綁卡選項
3. 可下分上限 (玩家要出資的 建議不設上限，玩家沒出資的 建議設上限)
4. 參加流程，提示本金、贈金、通過條件
5. 儲n送m，老帶新、限遊戲(電子)
6. 登記制或查詢制都可做到，查詢制要加限制避免被衝爆(ex: 回覆30min內有變化的會員)

### 活動參加流程

sequenceDiagram

actor pl as 會員
participant h1 as 官網
participant cpf as 活動前台
participant cp as 活動API

pl->>+h1 : 進入活動頁面
h1->>cp : 取得活動列表跳轉連結
cp-->>h1 : 返回活動連結 包含JWT
h1-->>pl : 跳轉嵌入頁面

alt 瀏覽活動列表
pl->>cpf : 瀏覽活動列表
cpf->>+cp : 檢查參加資格
cp->>+h1 : 查詢參加資格需要的資料
h1-->>-cp : 返回參考資料
cp-->>-cpf : 返回活動列表
cpf-->>pl : 顯示活動列表
end

alt 參加活動
pl->>cpf : 選定參加活動
cpf->>cp : 登記活動
cp-->>cpf : resp
cpf-->>pl : resp

cp->>h1 : 活動優惠上分
end

### 站長設定活動

sequenceDiagram
actor ag as 代理
participant h1 as 代理後台
participant cpb as 活動後台
participant cp as 活動API

ag ->> h1 : 進入活動管理系統
h1 ->> cp : 取得管理系統跳轉連結
cp -->> h1 : 返回活動管理系統連結 包含JWT
h1 -->> ag : 跳轉活動管理系統
ag ->> cpb : 跳轉

### 更新流程

* 查詢型

sequenceDiagram

participant h1 as 官網
participant cp as 活動

cp ->> h1 : 詢問會員活動必要資料
h1 -->>+ cp : 返回資料
cp ->>- cp : 更新狀態

* 登記型

sequenceDiagram

actor pl as 會員
participant h1 as 官網
participant gs as 遊戲
participant cp as 活動

pl->>h1 : 進入遊戲
pl->>gs : 下單
pl->>h1 : 離開遊戲
h1->>gs : 拉注單排程
gs-->>h1 : resp
h1->>cp : 登記流水贏分輸分充值
note over h1, cp: {memberID, reportDatetime,<br/> turnovers: [{gameID, turnover}, ...],<br/> winnings: [{gameType, gameID, win}, ...],<br/> loses: [{gameID, lose}, ...]}
cp-->>h1 : 通過/未通過

### 充值流程

sequenceDiagram

participant fp as 代收系統
actor pl as 會員
participant h1 as 官網
participant h1s as Server

pl ->> h1 : 使用充值功能
h1 -->> pl : 渠道選擇頁面
alt 人工處理
pl ->> h1 : 選擇人工處理
h1 -->> pl : 回應匯款資訊
pl ->> h1 : 提交資訊
else 代收系統
pl ->> h1 : 選擇代收系統
h1 -->> pl : 跳轉地址
alt 支付流程
pl ->> fp : 跳轉處理
fp ->> h1s : 成功回調
end
end
h1s ->>+ h1s : 開立洗碼單
h1s ->>- h1s : 會員上分

### 提款流程

sequenceDiagram

actor pl as 會員
participant h1 as 官網
participant cp as 活動
participant h1b as 後台
actor ag as 代理/客服/會計/Robot
participant nb as 網銀

pl ->> h1 : 提款
h1 ->> cp : 查詢活動保留點數
cp -->> h1 : 保留點數
h1 -->> pl : 可提款餘額
pl ->> h1 : 提交提款單
h1 ->> h1b : 提示提款單請求
h1 -->> pl : 提交成功等待審核
alt 客服作業
ag ->> h1b : 客服審核(處理中)
end
alt 會計作業
ag ->> h1b : 會計處理
ag ->> nb : 轉帳
ag ->> h1b : 設置為完成
end

## API

從舊皇發生的視角

### 進入 Incoming

#### /api/promotion/records/:playerID/:begin
從`begin`起始時間，取得`PlayerID`資料，匯總有效壓分、匯總贏分、匯總輸分、匯總充值

#### /api/:provider/rewards
參與活動時贈金回調
Method: **POST**
Header: **content-type: application/json**
Request:

{
    payload: {
        "@state",
        state: 0,
        out_trade_no: "AA6BF5D0-FD4B-4E78-A2E4-6DA712C4A692", // 交易代號
        trade_no: "3E5C3FFA-146D-4660-A601-7B265256175A", // 支付系統服務單據號
        ts: 1657497660000,  // 交易時間戳(ms)
        amount: 500, // 金額 正數為充值 負數為提取
        request_amount: 500,
        ip: "123.45.67.89" // 使用者 IP
    },
    signature: "7807f21c7bae619bca329d9944900458"
}

### 外出 Outcoming

#### /passports/agent
取得跳轉到活動管理界面的連結或api使用的token

{
    payload: {
        agent_id: "20CCA0D9-5C45-45AA-A6AD-4EEB89B97079",
        agent_name: "Agent name",
        lang: "th-TH",
        ts: 1657497660000
    },
    signature: "80752c3932f430102b14dfb7d9a4eb5e"
}

#### /passports/player
取得玩家用的token, `agentID` `playerID`

{
    payload: {
        agent_id: "0CCA0D9-5C45-45AA-A6AD-4EEB89B97079",
        agent_name: "Agent name",
        user_id: "014A5FE4-ED31-4020-A929-51FE9D4EFAD6",
        user_name: "User name",
        out_trade_no: "AA6BF5D0-FD4B-4E78-A2E4-6DA712C4A692",
        callback_url: "https://api.myhost.com/api/WireTransferRespond/<provider>",
        lang: "th-TH",
        ts: 1657497660000
    },
    signature: "77521395828ff826401214ebf98c1161"
}

#### /promotions/
取得`agentId`底下的活動列表，並附帶`playerId`的參與狀況與進度
相關資訊由jwt提供

#### /promotions/:ID
參加活動，系統對當前jwt的會員生成一筆對這個活動的參加記錄
需帶入資料 `agentId` `playerId` `rewardUrl`

#### /records
由平台主動登錄玩家記錄，含`有效投注` `總贏分` `總輸分`

{
    payload: {
        user_id: "014A5FE4-ED31-4020-A929-51FE9D4EFAD6",
        user_name: "User name",
        meta: {
            date_registered: "2022-10-19 10:23:45",
            first_deposit: 1000,
            descendants: 9,
        },
        records: [
            {genre: "summary", provider: "platform", type: "all", game: "all", turnover: 100000, netWin: 5000, win: 5500, lose: -500},
            {genre: "specific", provider: "jdb", type: "slot", ...values},
            {genre: "specific", provider: "jdb", type: "casino", ...
        ]
    }
}

## 洗碼模組

目的在開發成子系統，提供主系統附屬功能，並適當分擔主系統資料庫負擔。
資料取得模式希望可用登記式

### DB(選項)
資料庫版本: Postgress
用途: 這個DB(查詢式)

erDiagram

t_member ||--o{ t_rolling_accumulated : extends
t_rolling_accumulated }|--|{ t_configurations : use

t_rolling_accumulated {
  string member_id
  string agent_id
  string rolling_id
  number rolling_target
  number rolling_accumulated
  int status
  datetime begin_at
  datetime update_at
  datetime finish_at
}

t_configurations {
  string key
  string value
  string comment
}

#### 洗碼狀態
| status | 資料表 | key | 說明
|---- |---- |---- |----
| | t_configurations | rolling_status.rolling | 洗碼中
| | t_configurations | rolling_status.completed | 已完成
| | t_configurations | rolling_status.canceled | 已取消

#### 洗碼類型
| status | 資料表 | key | 說明
|---- |---- |---- |----
| | t_configurations | rolling_type.deposit | 洗碼中
| | t_configurations | rolling_type.withdraw | 已完成
| | t_configurations | rolling_type.reward | 贈金
| | t_configurations | rolling_type.rolling | 洗碼

### API

### /rollings/agent/:agent_id/setting `post`
設定代理參數，多一層加權值(預設1倍)，對充值要產生的洗碼目標
只對後續的洗碼生效，
可以用於洗碼加倍限期活動

{
    payload: {
        agent_id,

        ts,
    },
    signature,
}

#### /rollings/member `get`
取得所有會員

{
    records: [
    {status, member_id, target, rolled},
    {status, member_id, target, rolled},
    //...
    ],
    pagination: {
      total_rows, limits, page, pages
    }
}

#### /rollings/member/:member_id `get`
取得會員洗碼狀態

> response
> [status: 洗碼狀態](#洗碼狀態)

{
    status,
    member_id,
    target,
    rolled,
}

#### /rollings/member/:member_id `post`
調整會員洗碼量(充值、提取、贈金、有效壓分)

{
    payload: {
        type, 
        amount,
        ts,
    },
    signature, 
}

> [type: 洗碼類型](#洗碼類型)

#### /rollings/member/:member_id/force_cancel `post`
強制取消當前洗碼單

{
    payload: {
        reason: "string",
        ts: 1234567890,
    },
    signature: "string",
}