隨付即用（PAYG）· Agent 展示 —— 接口需求单

① 一个校验端点（门户匿名可调，与其余 portal 端点同层）：

POST /api/amlPortal/Promo/portal/VerifyPromoCode
{ "Code": "FREEQ2026", "CountryCode": "HKG", "Scene": "PayAsYouGo" }

→ { "code": 0, "data": {
      "code": "FREEQ2026",
      "kind": "Free",            // Free | Percent | Amount —— 前端按 kind 分流
      "value": 0,                // Percent: 折扣率；Amount: 直减额；Free: 0
      "currencyCode": "HKD",     // kind=Amount 时必需
      "labelEN": "...", "labelCN": "...", "labelJP": "...",
      "validTo": "2026-12-31T23:59:59",
      "remainingCount": 998      // 可为 null（不限量）
   } }

② CreatePayAsYouGoOrderParam 增 PromoCode，后端建单时再验一次并自行算价（前端传来的金额一概不采信），把 PromoCode / DiscountAmount / 实际应付额落到 Order 上。

前端目前只用得上 kind: "Free" 一种 —— 页面流程是「有码就不用付款」。折扣型（打完折还要收余额）会多出一条分支，等后端把规则定下来再一起做，接口先把 kind 留出来即可。

• OrderService.cs:1835 —— 必填校验已被注释掉；
• OrderService.cs:1899 —— 仍是 SubjectName = input.SubjectName.Trim()，传 null 直接 NullReferenceException；
• ActivatePaygOrder 用 order.SubjectName 作 ConsumerCustomer.Name 建检测链接；
• UpdateOfflinePaygOrder 仍强制 SubjectName 非空 —— 管理端确认线下收款前必须先补一个主体名。

• 同一套筛选逻辑写了两份，改一处漏一处就会出现「页面标价」与「实际结算价」不一致；
• 标签是后台可配的自由文本 —— 运营改一次标签，页面就静默变成「暂无价格」，没有任何报错；
• 某市场若配出两条 SP，取到哪条取决于返回顺序。

POST /api/amlPortal/plan/portal/GetPayAsYouGoOffer
{ "CountryCode": "HKG" }

→ { "code": 0, "data": {
      "planId": "...", "planDetailId": "...",
      "price": 200, "taxAmount": 0, "currencyCode": "HKD",
      "nameEN": "Pay-As-You-Go", "nameCN": "隨付即用", "nameJP": "従量課金",
      "functionCodes": ["V","E","A","D"],      // 见 A7
      "isAvailable": true                       // 该市场是否开售，见 A9
   } }

要点是「本市场的隨付即用卖什么价」这个判断由后端一次给准，前端不再需要知道 tag 体系的存在。

POST /api/amlPortal/Order/portal/QueryPaygOrder
{ "OrderCode": "P26...", "ContactEmail": "a@b.com" }   // 邮箱作为轻量校验，防止按单号枚举

→ { "code": 0, "data": {
      "orderCode": "...", "orderStatus": 400, "paymentStatus": 1,
      "linkIssued": true, "linkSentTo": "a***@b.com",
      "canResendLink": true
   } }

配套一个 ResendPaygLink（同样带邮箱校验 + 频率限制）就能把「没收到邮件」这条最常见的客诉在页面上自助解决。

• 做完 B1 后，前端就不再需要这个端点（BFF 会把这段扇出删掉）—— 届时请把它收回鉴权，或至少禁掉匿名下的模糊匹配；
• 若仍要保留匿名可调，请换成 portal 专用的精简 DTO（只给 userCode / name / agentRemark），别把 AppUserDto 直接吐出来。

• 停用/离职的代理仍会公开展示，而且可被选中下单 —— 线下单会派给一个已经停用的账号；
• 遍历的是 AgentUserSetting 而不是用户：同一 agent 在同一国家有两条设置记录时，卡片会重复出现两张。

若产品上希望「代理展示」是一块真正的展示位（而不只是一个选择器），需要后端在 AgentUserSetting 或用户扩展属性上补字段，并从门户 DTO 返回。建议字段：

另需确认 AgentRemark 的换行/富文本口径：邮件侧已经在做 \n → <br /> 的转换（EmailMessageService.cs:1302），而网页侧是纯转义输出（防 XSS），所以代理在后台敲的换行到了官网会被压平成一段。要么约定它是纯文本（后台输入框也别让人换行），要么约定它保留换行、由前端按行渲染。