justsolutionsWebV2 · plans-plus 真實 API 對接分析

1. 結論速覽

plans-plus 前端共依賴 7 個業務端點（外加支付狀態輪詢 / webhook 2 個）。其中大部分可直接復用旧站 justsolutionsWeb 已經對接好的同一批 AMLPortal 後端端點；落地工作主要是在 justsolutionsWebV2/server/routes/ 新增 BFF 處理器，做「後端原始響應 → 前端精簡契約」的字段轉換（與既有 countries.js / industries.js 完全同一範式）。

2. 總體架構與調用鏈

justsolutionsWebV2 採「BFF（Backend-for-Frontend）」式：瀏覽器只調用本站 /api/*，由 Node/Express 依 APP_ENV 決定走 mock 還是真實後端，前端代碼零改動即可切換環境。

• 前端封裝 public/js/api.js：api.get('/editions') 實際請求 /api/editions。所有 plans-plus 端點均走此封裝。
• 環境切換 server/config.js：mockEnabled = (APP_ENV==='test')；真實環境需配 API_BASE_URL 與 OAuth 憑證（.env.*）。
• 掛載順序 server/index.js：真實環境先掛 routes/*.js 業務路由，再掛 proxy 兜底；mock 環境掛 mock/routes.js。新增 plans-plus 的真實路由就照此追加 app.use(apiPrefix, createXxxRouter(config))。
• 鑑權 server/services/auth.js：OAuth2 password 流程取 token 並緩存（提前 5 分鐘刷新），對應旧站硬編碼的 customer1 訪客憑證，現改為 .env 配置。BFF 每次調後端用 createAuthConfig() 加 Authorization: Bearer。

3. plans-plus 前端依賴的 API 契約

以下是 plans-plus.js 實際讀寫的字段（即 BFF 必須產出/接受的契約，目前由 mock/routes.js 滿足）。真實對接時 BFF 輸出必須與此逐字段一致，否則前端渲染/計價會出錯。

3.1 載入期（頁面初始化並發拉取）

loadAll() 並發請求 /editions、/plans/catalog、/countries，三者均以 { success:true, data:… } 為成功標誌。

GET /editions     → { success, data:{ editionList:[{id, displayName, nameCN, nameJP}],
                                       jQSeparatedEditions:{ editionIds:[…] } } }
GET /plans/catalog→ { success, data:{ standard:[Plan], cpa:[Plan], addons:{
                       user:{unitPrice,…}, kyc:{unitPrice,…},
                       jquota:{ packages:[{id, jq, price, nameCN/EN/JP}] } } } }
GET /countries    → { success, data:[{code, name, nameTC, nameSC, nameJP, phoneCode}] }

Plan = { planId, tag2Code, nameCN, nameEN, nameJP, periodMonths,
         price, originalPrice, qCount(-1=無限), userCountLimit,
         bestValue, noteCN, noteEN, noteJP }

3.2 交互期（按需）

GET /tenants/lookup?email=&name=
   → { success, match:'none'|'unique'|'multiple',
       tenant:Tenant|null, candidates:[{tenantId, tenantName}] }
GET /agents/:code  → { success, found:bool, data:{code, name}|null }

Tenant = { tenantId, tenantName, editionId, editionName, jurisdiction, br, ci,
           currentSubscription:{ planId, nameCN/EN/JP, periodMonths, price,
             qCount, userCountLimit, startDate, expiryDate, usedQuota,
             addons:{ users:int, kyc:bool, jquotaPackageId:string } } }

3.3 提交期（兩步串聯）

submit() 先 POST /subscribe 拿 orderId，再 POST /payments/create 拿 redirectUrl 跳轉支付。

POST /subscribe  body = {
   type:'new'|'renew'|'topup', edition, isCpa, startDate,
   plan:Plan, planPrice, isRenewalRate,
   addons:{ users, userUnitPrice, kyc, kycUnitPrice,
            jquotaPackageId, jquotaPackageName, jquotaUnits, jquotaPrice },
   agentCode, subtotal, total,
   // type=new 追加： company, jurisdiction, br, contact, phoneCode, phone, email, address
   // type=renew/topup 追加： tenantId, company, email, currentSubscription
 } → { success, data:{ orderId, status, createdAt } }

POST /payments/create body = { orderId, amount, currency:'HKD', company, email }
   → { success, data:{ paymentId, status, gateway, redirectUrl } }

4. 後端真實端點清單（AMLPortal）

以下端點均在 AML_Backend/modules/iCON.Abp.AMLPortal，並已被旧站 justsolutionsWeb/PlanService 使用驗證過。前綴 /api/amlPortal/*，鑑權走 [AbpAutoAuth("Portal")]（門戶訪客 token）。

DTO 位置：Application.Contracts/PlanAppLayer/*（GetPlanListParam、PlanDto、PlanDetailDto）、Application.Contracts/OrderAppLayer/*（CreateOrderParam、SelectPlanItem、TenantRenewalParam、QueryRenewableTenantParam、TenantPropertyDto）。

5. 端點逐一映射與落地方案

每節：前端契約 → 對應後端 → 字段映射 → BFF 轉換要點 → 差異/缺口。新增的 BFF 文件建議放 server/routes/，與 countries.js 同範式（createAuthConfig() + axios + 字段映射 + {success,data} 包裝）。

5.1 GET /editions（所屬行業） 改造

後端返回 { code:0, data:{ editionList:[{id, displayName, …}], jQSeparatedEditions:{editionIds:[…]} } }。前端要 editionList:[{id, displayName, nameCN, nameJP}] 與 jQSeparatedEditions.editionIds。

5.2 GET /plans/catalog（方案目錄） 改造

BFF 以旧站同款請求體調 GetPlanList，再復刻旧站 filterPlan() 把扁平 items 按 tag1Code 拆成 5 組，組裝成 {standard, cpa, addons}。

請求體（沿用 PlanService.getAllPlanList）

{ pageIndex:0, pageSize:9999, filter:'', getAllItems:false,
  tag1List:['B','jQ','j','AdlU','KYC'], tag2List, tag3List, agentUserId }

後端 items → 前端 Plan 字段映射

addons 拆分（按 tag1Code）

• standard ← tag1Code==='B' && tag2Code!=='CPA'；cpa ← tag1Code==='B' && tag2Code==='CPA'
• addons.user.unitPrice ← tag1Code==='AdlU' 的 planDetails[0].price（並記其 planId/planDetailId 備下單）
• addons.kyc.unitPrice ← tag1Code==='KYC' 同上
• addons.jquota.packages[] ← tag1Code==='jQ'||'j'：每項 { id:planId, jq:qCount, price:planDetails[0].price, name* }，並各自記 planDetailId

5.3 GET /countries（註冊地） 已實現

server/routes/countries.js 已實現並可直接用：取 typeCodes:['COUNTRY']，從 categoryTranslations 提 zh-hk/zh-cn/ja/en-us，輸出 {code, name, nameTC, nameSC, nameJP, phoneCode}，正好滿足 plans-plus 的 countryDisplay() 與 phoneCode 自動填充。無需改動。

5.4 GET /agents/:code（推薦人代理） 改造

前端要 { success, found, data:{code, name} }。後端（Identity）返回匹配到的用戶（含 name/userName/extraProperties.code 等）。BFF 取首條 → found:true, data:{code, name}；無匹配 → found:false, data:null。

5.5 GET /tenants/lookup（續費查租戶） 缺口大

前端按郵箱查租戶，支持「none / unique / multiple」三態，命中後帶出 currentSubscription 預填續費表單。但後端 queryRenewableTenant 只接受 {keyword} 且按 TenantName.Contains(keyword) 搜索（OrderService.cs:2363），返回 List<TenantPropertyDto>（內部已把 admin 郵箱填入 TenantAdminEmail）。

兩個不匹配點

1. 查詢維度不符：前端給郵箱，後端按名字搜。
   短期 BFF 變通：以空/寬 keyword 拉取後在服務端按 TenantAdminEmail===email 過濾並按郵箱分組（⚠️ 全量拉取、性能與越權風險，僅臨時）。
   正解：後端新增「按管理員郵箱查可續費租戶」端點（返回同 TenantPropertyDto 結構）。
2. currentSubscription 需重建：前端的 currentSubscription（planId、name、periodMonths、price、qCount、userCountLimit、startDate、expiryDate、usedQuota、addons）並非 TenantPropertyDto 直接字段，需由 TenantProperty + 其 Order + 正在生效的 plan 推導。可參考 GetCurrServiceInfo（CurrServiceInfoDto.ActiveBPlans、EffectiveEndTime、QCountLeft 等）。

TenantPropertyDto → 前端 Tenant 映射（可得部分）

5.6 POST /subscribe（下單） 改造

BFF 依 body.type 分流到不同後端端點，並把前端的「人類友好」payload 翻成後端 DTO；核心是組裝 PlanList（基礎方案 + 各加值項，每項補 planDetailId）。

① type='new' → CreateOrder

② type='renew' → TenantRenewal

③ type='topup' → 新增需求 · 無對應端點

純加購（無基礎方案，只買 增加用戶/KYC/jQuota）。後端無直接端點。候選方案：

• A（推薦）：復用 TenantRenewal，PlanList 只含加值項（不含 B 類基礎方案），由後端確認是否允許「無基礎方案」的續費單並只疊加配額/開關。需後端確認語義。
• B：後端新增 TenantTopup 端點，明確「在現有有效訂閱上疊加配額/用戶/KYC，不延長有效期」。UpdateTenantProperty（admin）邏輯可借鑒（它就是疊加 PlanList 並重算配額），但屬 admin 線下流程。

PlanList 組裝（三種 type 共用，核心難點）

PlanList = []
// 基礎方案（topup 不加）
if (type!=='topup') PlanList.push({ PlanId: plan.planId,
                                    PlanDetailId: plan.planDetailId, PCS: 1 })
// 增加用戶：PCS = addons.users
if (addons.users>0) PlanList.push({ PlanId: AdlU.planId,
                                    PlanDetailId: AdlU.planDetailId, PCS: addons.users })
// KYC：PCS = 1
if (addons.kyc)     PlanList.push({ PlanId: KYC.planId,
                                    PlanDetailId: KYC.planDetailId, PCS: 1 })
// jQuota：選中的配套 ×1
if (addons.jquotaPackageId)
                    PlanList.push({ PlanId: jqPack.planId,
                                    PlanDetailId: jqPack.planDetailId, PCS: 1 })

5.7 POST /payments/create（支付） 缺口大

旧站沒有獨立的 create-payment 後端端點：plan4.component.payFn() 在前端直接用 orderCode/planName/txamt 拼 QFPay checkstand URL 並 sha256 簽名後 location.href 跳轉。plans-plus 改成調 /payments/create 拿 redirectUrl ⇒ 這段簽名邏輯應移到 BFF 服務端（API key 不可暴露前端）。

BFF 實現要點（對標旧站 QFPay 參數）

BFF 返回 { success, data:{ redirectUrl:<QFPay checkstand URL> } }，前端 location.href 跳轉。支付結果由 QFPay 異步回調後端 PaymentWebhook 落單（權威來源）；前端返回頁可輪詢訂單狀態。

6. plans-plus 相對旧站的新增需求

以下是 plans-plus 單頁流程相對旧站 4 步嚮導新增或改變的點，逐一標注對接影響。

7. 實施建議與分期

7.1 新增 / 改動文件清單（justsolutionsWebV2/server）

7.2 可能的後端改動（建議與後端團隊確認）

• 按郵箱查可續費租戶端點，返回聚合 currentSubscription（含 planId / 上期 price / 已購加值項）。
• topup 語義：明確「無基礎方案的加購」如何下單（TenantRenewal 是否允許 / 新增 Topup 端點）。
• （可選）Plan 增 bestValue 與多語言 note；edition 增多語言名稱。

7.3 建議分期

8. 待確認問題清單

1. 租戶查詢：後端能否新增「按管理員郵箱查可續費租戶」？返回是否能直接帶 currentSubscription（planId / 上期價 / 已購加值項）？
2. topup：純加購走 TenantRenewal（PlanList 僅加值項）後端是否接受、語義是否「只疊配額不延期」？還是需新端點？
3. BR/CI：plans-plus 把 BR 標為可選，但後端要求 BR 或 CI 至少一個——UI 是否補 CI 字段，或把 BR 設為必填？
4. bestValue / note / edition 多語言：由 BFF 配置維護，還是後端在數據上補字段？
5. QFPay：V2 是否沿用旧站同一 appcode/api_key/收銀台域名？簽名算法是否一致（sha256 排序串 + key）？
6. 0 元 / P2G：免支付分支的判定（paymentStatus===200 或 txamt===0）是否照搬？
7. agentorId：/agents/:code 響應是否可附帶 agent 的 Guid id，避免下單時二次查詢？
8. 鑑權憑證：V2 BFF 用的門戶訪客 OAuth 帳號（.env）權限是否覆蓋 CreateOrder / queryRenewableTenant（均 [AbpAutoAuth("Portal")]，應可）？