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

1. 結論速覽（含本次更正）

plans-plus 前端目前依賴 3 條「只讀目錄」端點（editions / plans/catalog / countries）、2 條「交互查詢」端點（agents / tenants/lookup）、1 組單次查詢端點（single-query，新）、2 條「下單提交」端點（subscribe / payments）、以及 1 條「聯絡我們」通知端點（contact——不創建訂單，僅發送訂單摘要），共 4 種訂閱流程：new（新購）、renew（續費）、topup（加購）、single（按次查詢）。

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')；另有 plansPlusMock（PLANS_PLUS_MOCK）開關——在真實環境下仍讓 plans-plus 這組端點走 mock，其餘 /api/* 透傳後端。真實對接時把它置 false，並在 server/routes/ 補齊業務路由。
• 掛載順序 server/index.js：真實環境依次掛 contact / trial-application / industries / countries 路由，再按 plansPlusMock 決定是否掛 mock，最後掛 proxy 兜底。新增 plans-plus 真實路由就照此在代理之前追加 app.use(apiPrefix, createXxxRouter(config))。
• 鑑權 server/services/auth.js：OAuth2 password 流程取 token 並緩存（提前 5 分鐘刷新），對應旧站硬編碼的門戶訪客憑證，現改為 .env 配置（AUTH_USERNAME/PASSWORD/CLIENT_ID/...）。BFF 每次調後端用 createAuthConfig() 加 Authorization: Bearer。

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

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

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

並發請求 /editions、/plans/catalog、/countries、/single-query/options，四者均以 { 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, name* },
                       kyc:{ monthlyPrice, name* },                 // ← 改為「月租」
                       jquota:{ packages:[{id, jq, price, name*}] } } } }
GET /countries    → { success, data:[{code, name, nameTC, nameSC, nameJP, phoneCode}] }
GET /single-query/options → { success, data:{ operations:[
                       {id, price, nameCN/EN/JP, descCN/EN/JP}] } }   // ← 新

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

3.2 交互期（按需）

GET /tenants/lookup?email=          // ← 只按郵箱；郵箱全局唯一 → 至多命中 1 個租戶
   → { success, match:'none'|'unique', tenant:Tenant|null }
      // 註：前端已不再做「一郵箱多租戶」消歧；舊契約的 match:'multiple' / candidates[] 已廢棄
GET /agents/:code
   → { success, found:bool, data:{ code, name, tiers:[tag2Code…], email, phone }|null }
      // tiers：該推薦人可售的方案級別（P2G/Std/Pre/CPA），前端據此再過濾行業方案集

Tenant = { tenantId, tenantName, editionId, editionName, jurisdiction, br, ci,
           referrer:{code,name}|null,                    // ← 註冊時填寫的推薦人，續費頁展示
           currentSubscription:{ planId, nameCN/EN/JP, periodMonths, price,
             qCount, userCountLimit, startDate, expiryDate, usedQuota,
             addons:{ users:int, kyc:bool, jquotaPackageId:string } } }

3.3 提交期

submit()（在線下單）與 submitContact()（聯絡我們/推薦人）共用 collectPayload() 收集當前表單。本輪支付除外——submit() 只 POST /subscribe，成功即顯示「已提交成功」；submitContact() 不創建任何訂單，把訂單摘要 POST 到聯絡端點（見 5.8），成功後顯示「已收到資料，將盡快聯絡」。（現網代碼仍 POST /subscribe-offline；本次語義調整後應改走 contact us API，見 5.8「與現網代碼的差異」。）

POST /subscribe  body = {
   type:'new'|'renew'|'topup', edition, isCpa, startDate,
   plan:Plan, planPrice, isRenewalRate,
   addons:{ users, userUnitPrice,
            kyc, kycUnitPrice, kycRentalMonths,                    // ← 含租賃月數
            jquotaPackageId, jquotaPackageName, jquotaUnits, jquotaPrice },
   agentCode, subtotal, total,
   // type=new 追加： subjectType('corp'|'individual'), company, jurisdiction, br,
   //                contact, phoneCode, phone, email, address
   //                （個人主體：contact=company，br/address 恒為空）
   // type=renew/topup 追加： tenantId, company, email, currentSubscription
 } → { success, data:{ orderId, status, createdAt } }

POST /contact  body = {              // ← 聯絡我們/推薦人：不創建訂單，僅發送摘要
   name, email, company,            // 客戶聯絡人 / 郵箱 / 公司(租戶/主體)名
   subject:'訂閱諮詢 · {type}',       // 可帶方案名
   message: ,
   agentUserId?                      // 有推薦人時附帶其後端 Guid → 後端解析郵箱、收件人改為該推薦人
 } → { success, data:{ feedbackId } }

POST /single-query body = {
   type:'single', subjectType:'individual'|'company', subject, email,
   operations:[{id, name, price}], total
 } → { success, data:{ orderId, status, createdAt } }

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

以下端點均在 AML_Backend/modules/iCON.Abp.AMLPortal，並已被旧站 justsolutionsWeb/PlanService 使用驗證過。前綴 /api/amlPortal/*（agent 校驗端點在 Identity 模塊 /api/identity/*）。

DTO 位置：Application.Contracts/PlanAppLayer/*（GetPlanListParam、PlanDto、PlanDetailDto）、Application.Contracts/OrderAppLayer/*（CreateOrderParam、SelectPlanItem、TenantRenewalParam、QueryRenewableTenantParam、TenantPropertyDto）。agent 返回 DTO：iCON.Abp.FX.Users/AppUserDto。

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

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

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

後端返回 { code:0, data:{ editionList:[完整 Edition 實體], jQSeparatedEditions:{ EditionIds:[…], EditionNames:[…] } } }（OrderService.cs:1103 直接把 SaasEdition 實體與 _appConfig.Portal.jQSeparatedEditions 原樣返回）。前端要 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:null }
  // 後端 GetPlanList 對 Tag2List/Tag3List：命中或 Tag2Code 為空皆放行（OrderService/PlanService:78-80）

後端返回 { code:0, data:{ totalCount, items:[PlanDto{…, planDetails:[PlanDetailDto]}] } }（PlanService.cs:107 PagedResultDto<PlanDto>）。注意：getAllItems:false 時後端已過濾 Enabled 且僅保留在有效期內的 planDetails（PlanService.cs:99-104）。

後端 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.monthlyPrice ← tag1Code==='KYC' 的 planDetails[0].price（當作月租單價，見下方 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 自動填充。無需改動（種子含 249 個國家）。

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

前端要 { success, found, data:{ code, name, tiers:[tag2Code…], email, phone } }。後端 SearchUserByCodeAndType 按 UserCode 精確匹配，返回 List<AppUserDto>（{Id, UserName, Email, Name, Surname, PhoneNumber, ExtraProperties}）。BFF 取首條做轉換；無匹配 → found:false。

5.5 GET /tenants/lookup（按郵箱查租戶） 缺口大

前端按郵箱查租戶，返回 match:'none'|'unique' 兩態（不再多租戶消歧——註釋明確「租戶名與郵箱均全局唯一 → 一郵箱至多 1 個租戶」）。命中後帶出 currentSubscription + referrer 預填續費/加購表單。

但後端 queryRenewableTenant 只接受 {keyword} 且按 TenantName.Contains(keyword) 搜索（OrderService.cs:2362），返回 List<TenantPropertyDto>——TenantAdminEmail 是查完後再逐條用 admin 用戶郵箱回填（:2375-2379），不能在 DB 層按郵箱過濾。

三個不匹配點

1. 查詢維度不符：前端給郵箱、後端按名字搜。短期 BFF 變通：以空/寬 keyword 拉全部可續費租戶，在服務端按 TenantAdminEmail===email 過濾（⚠️ 全量拉取、性能與越權風險，僅臨時）。正解：後端新增「按管理員郵箱查可續費租戶」端點。
2. currentSubscription 需重建：前端的 currentSubscription（planId、name、periodMonths、price、qCount、userCountLimit、startDate、expiryDate、usedQuota、addons）並非 TenantPropertyDto 直接字段，需由 TenantProperty + 其 Order/OrderDetail 推導。可參考 GetCurrServiceInfo（OrderService.cs:398，CurrServiceInfoDto）。
3. referrer 新增：前端續費頁展示「註冊時填寫的推薦人」。TenantPropertyDto 已有 AgentorCode/AgentorName ⇒ 映射為 referrer:{code:AgentorCode, name:AgentorName}。

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

5.6 單次查詢 single-query（按次付費） 新增需求 · 後端零支持

plans-plus 新增第 4 種流程 type='single'：無需訂閱、填「結果接收郵箱 + 查詢主體 + 勾選查詢項目」→ 付款 → 結果郵件發送。前端契約見 3.1/3.3。全庫 grep 無任何按次查詢 / pay-per-use 端點或實體。

• GET /single-query/options：返回查詢項目目錄 operations:[{id, price, name*, desc*}]（制裁篩查、PEP、負面新聞、公司查冊、身份核實…）。
• POST /single-query：建按次查詢訂單，返回 orderId，本擬走與訂閱相同的支付鏈（本輪支付除外）。

5.7 POST /subscribe（下單） 改造

BFF 依 body.type 分流；核心是組裝 PlanList（基礎方案 + 各加值項，每項補 planDetailId）。

① type='new' → CreateOrder

② type='renew' → TenantRenewal

續費續價：後端按 planDetail 的 Price 計；前端的「續費續價（沿用上期 price）」屬展示層優惠，後端不認前端傳入的 price。若要真正續價，需後端支持自定義價 / 專屬續費 PlanDetail——本輪按目錄價下單，前端續費折扣僅為展示（待業務確認）。

③ type='topup' → TenantRenewal（僅加值項） 需後端確認語義

純加購（無基礎方案，只買 增加用戶/KYC/jQuota）。後端無專屬端點。候選 A（推薦）：復用 TenantRenewal，PlanList 只含加值項（不含 B 類）。源碼上 TenantRenewal 只對 Tag1Code==='B' 的行設服務起止期（:2300-2314），非 B 行只疊加配額/用戶 ⇒ 理論上「只疊配額不延期」語義成立，但需確認 ProcessTenantEventQueue 下游對「無 B 行的續費單」處理正確。候選 B：後端新增 TenantTopup（可借鑒 admin 的 UpdateTenantProperty :2389，它就是疊 PlanList 重算配額）。

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 = kycRentalMonths（把 KYC planDetail.price 當月租單價；見 5.2）
if (addons.kyc)     PlanList.push({ PlanId: KYC.planId,
                                    PlanDetailId: KYC.planDetailId, PCS: addons.kycRentalMonths })
// jQuota：選中的配套 ×1
if (addons.jquotaPackageId)
                    PlanList.push({ PlanId: jqPack.planId,
                                    PlanDetailId: jqPack.planDetailId, PCS: 1 })

5.8 聯絡我們/推薦人（發送訂單摘要 · 不創建訂單） 復用現有 contact API

訂單摘要下方的「聯絡我們 / 聯絡推薦人」按鈕與付款按鈕同樣的有效性門檻（由 updateSubmitEnabled() 控制），但不創建任何訂單/租戶/線索——只是把用戶當前已填寫的訂單摘要（collectPayload() 產出的 type/行業/方案/加值項/期間/總價與聯絡資料）整理成一段留言，經既有 contact us API 發出，讓管理員（或推薦人）主動跟進。成功後前端顯示「已收到資料，將盡快聯絡」（showOfflineSubmitted()）。

收件人路由：管理員 vs 推薦人

• 未填推薦人（或 type≠'new'）：發給平台管理員——即現有 CreateFeedback 的既定收件邏輯（後端反饋 + ADMIN_EMAIL 通知，contact.js:17）。
• 已填有效推薦人代碼（state.agent 已解析；前端 hasReferrer() 僅在 new 流程為真）：改發給該推薦人。推薦人 email/phone 已由 /agents/:code 帶出（見 5.4），前端可隨摘要一併提交。

5.9 POST /payments/create（支付） 本輪除外

當前 plans-plus.js 的 submit() 已臨時移除支付鏈：/subscribe 成功後直接 showSubmitted() 顯示「已提交成功」，不調 /payments/create、不跳收銀台。⇒ 本輪不實現支付端點。

後端側：在線非 0 元訂單 CreateOrder/TenantRenewal 目前走 MockupPayment(newOrder)（本地佔位、非真實支付方），配合 PaymentWebhook（端點 10）。真實支付（QFPay 收銀台簽名 URL + webhook）留待後續階段；屆時 QFPay 簽名邏輯應在 BFF 服務端完成（API key 不可暴露前端），mock 的 pay-gateway/pay-return//payments/:id 輪詢鏈可作參照。

6. 本地開發環境對接（docker-compose-local-dev）

本地棧（AML_Backend/docker-compose-local-dev/）已把後端 iCON.Abp.FX.HttpApi.Host 起在 http://localhost:44331（Swagger 同址），SQL Server 在 localhost,11433。要把 V2 的 plans-plus BFF 指到它，需三件事：配 .env、對齊 Portal 訪客憑證、補種子數據。

6.1 V2 側配置（把 BFF 指向本地後端）

# 便捷腳本（已加入 package.json）：APP_ENV=dev + 本地後端 + plans-plus mock 兜底 + PORT 8090
npm run start:local
# 等價於：
cross-env APP_ENV=dev API_BASE_URL=http://localhost:44331 PLANS_PLUS_MOCK=true PORT=8090 node server/index.js

6.2 種子數據缺口（對接前必補）

本地庫當前（實測）：

6.3 本輪落地狀態（已實現 · 2026-07 實測通過）

端到端驗證（npm run start:local + 本地 docker 後端）：/editions（10 行業 + CPA 切換）· /plans/catalog（standard/cpa/addons 全對）· /countries（249）· /agents/:code（無數據 found:false）· /subscribe（new 各變體均返回 orderId、訂單入庫）。頁面 GET /plans-plus HTTP 200。

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

8. 實施建議與分期

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

8.2 可能的後端改動（與後端團隊確認）

• BR/CI 必填：是否按 plans-plus 需求去除 CreateOrder 的 BR/CI 必填校驗（或僅對個人主體放開）。
• 按郵箱查可續費租戶端點，返回聚合 currentSubscription（含 planId / 上期 price / 已購加值項）+ referrer。
• topup 語義：確認 TenantRenewal（PlanList 僅加值項）是否「只疊配額不延期」，或新增 TenantTopup。
• KYC 計費口徑：確認 KYC plan 是否可按 PCS=月數 計月租。
• single-query：是否新增後端按次查詢端點，還是短期 mock。
• 聯絡我們送推薦人：待實現 已定方案——後端 CreateFeedback 增 AssignedAgentUserId 收件人字段（DTO + 實體 + 服務解析郵箱 + EF 遷移）：有值發推薦人、否則發平台銷售。
• （可選）Plan 增 bestValue/多語言 note/nameJP；edition 增多語言名稱。

8.3 建議分期

9. 待確認問題清單

1. BR/CI 必填：關鍵 後端 CreateOrder 仍要求 BR 或 CI 至少一個（OrderService.cs:154,190）。plans-plus 新購（含個人主體）需不填也能下單——是否去除該校驗？還是前端把 corp BR 改必填、個人主體暫不開放？
2. 單次查詢：後端是否新增按次查詢（options + 下單 + 計費 + 結果投遞）？本輪是否先保留 mock？
3. 聯絡我們（不下單）：已定方案 復用 contact/CreateFeedback 發送訂單摘要（不創建訂單/線索）；「送推薦人」擬由後端 CreateFeedback.AssignedAgentUserId 承接（待實現，見 5.8）。待辦：後端加字段 + 服務路由 + EF 遷移；前端調用點由 /subscribe-offline 改 POST /api/contact 並透傳 agentUserId；BFF 映為 AssignedAgentUserId。
4. 租戶查詢：能否新增「按管理員郵箱查可續費租戶」，直接帶 currentSubscription（planId/上期價/已購加值項）+ referrer？
5. topup：純加購走 TenantRenewal（PlanList 僅加值項）後端是否接受、語義是否「只疊配額不延期」？
6. KYC 月租：KYC plan 是否可按 PCS=租賃月數 計費（planDetail.price 當月租單價）？
7. 續費續價：後端 TenantRenewal 是否支持沿用上期價/自定義價？否則前端續費折扣僅展示、實際按目錄價。
8. agent tiers：BFF 經 GetPlanList(agentUserId) 推導 tiers，還是改為服務端直接按 agent 過濾 catalog？
9. agentorId：/agents/:code 響應附帶 agent Guid id，避免下單時二次查詢？
10. 鑑權憑證：V2 BFF 門戶訪客帳號（Portal@iconsz.com，__tenant=Portal）權限是否覆蓋 CreateOrder / queryRenewableTenant / SearchUserByCodeAndType？
11. 本地種子：Plan/Edition 種子走臨時 SQL 還是入 AMLPortalDataSeedContributor？CPA edition GUID 是否同步進 appsettings.local.json？
12. bestValue / note / 多語言：由 BFF 配置維護，還是後端在數據上補字段？