feat(payment): support user-bound seven-discount offers

src/data/repositories/interfaces/ipayment_repository.ts

@@ -13,7 +13,7 @@ import type { Result } from "@/utils/result";
 
 export interface IPaymentRepository {
   /** 获取套餐列表。 */
-  getPlans(): Promise<Result<PaymentPlansResponse>>;
+  getPlans(commercialOfferId?: string): Promise<Result<PaymentPlansResponse>>;
 
   /** 获取本地缓存套餐列表。 */
   getCachedPlans(): Promise<Result<PaymentPlansResponse | null>>;
@@ -30,6 +30,7 @@ export interface IPaymentRepository {
     payChannel: PayChannel,
     autoRenew: boolean,
     recipientCharacterId?: string,
+    commercialOfferId?: string,
   ): Promise<Result<CreatePaymentOrderResponse>>;
 
   /** 查询支付订单状态。 */

src/data/repositories/payment_repository.ts

@@ -24,10 +24,10 @@ export class PaymentRepository implements IPaymentRepository {
   constructor(private readonly api: PaymentApi) {}
 
   /** 获取套餐列表。 */
-  async getPlans(): Promise<Result<PaymentPlansResponse>> {
+  async getPlans(commercialOfferId?: string): Promise<Result<PaymentPlansResponse>> {
     return Result.wrap(async () => {
-      const response = await this.api.getPlans();
-      await PaymentPlansStorage.setPlans(response);
+      const response = await this.api.getPlans(commercialOfferId);
+      if (!commercialOfferId) await PaymentPlansStorage.setPlans(response);
       return response;
     });
   }
@@ -62,12 +62,14 @@ export class PaymentRepository implements IPaymentRepository {
     payChannel: PayChannel,
     autoRenew: boolean,
     recipientCharacterId?: string,
+    commercialOfferId?: string,
   ): Promise<Result<CreatePaymentOrderResponse>> {
     const request = CreatePaymentOrderRequestSchema.parse({
       planId,
       payChannel,
       autoRenew,
       ...(recipientCharacterId ? { recipientCharacterId } : {}),
+      ...(commercialOfferId ? { commercialOfferId } : {}),
     });
     return Result.wrap(() => this.api.createOrder(request));
   }

src/data/schemas/chat/response/chat_send_response.ts

@@ -15,10 +15,10 @@ import { ChatImageSchema, ChatLockDetailSchema } from "../chat_payloads";
 export const CommercialActionSchema = z
   .object({
     actionId: z.string().min(1),
-    type: z.enum(["giftOffer", "privateAlbumOffer"]),
+    type: z.enum(["giftOffer", "privateAlbumOffer", "discountOffer"]),
     copy: z.string().min(1),
     ctaLabel: z.string().min(1),
-    target: z.enum(["giftCatalog", "privateZone"]),
+    target: z.enum(["giftCatalog", "privateZone", "discountConsent"]),
     ruleId: z.string().min(1),
   })
   .readonly();

src/data/schemas/payment/__tests__/payment_plan.test.ts

@@ -75,6 +75,8 @@ describe("PaymentPlan", () => {
       mostPopular: true,
       firstRechargeDiscountPercent: null,
       promotionType: null,
+      commercialOfferId: null,
+      commercialDiscountPercent: null,
     });
   });
 
@@ -190,6 +192,45 @@ describe("PaymentPlansResponse", () => {
       discountPercent: 0,
     });
   });
+
+  it("parses one user-bound commercial offer and its discounted plan", () => {
+    const response = PaymentPlansResponseSchema.parse({
+      commercialOffer: {
+        enabled: true,
+        commercialOfferId: "offer-1",
+        planId: "vip_annual",
+        discountPercent: 30,
+        pricePercent: 70,
+        expiresAt: "2026-07-24T08:00:00+00:00",
+        triggerReason: "price_objection",
+        message: "I got this private price for you.",
+      },
+      plans: [
+        {
+          planId: "vip_annual",
+          planName: "Annual VIP",
+          orderType: "vip_annual",
+          vipDays: 365,
+          dolAmount: null,
+          creditBalance: 9000,
+          amountCents: 12593,
+          originalAmountCents: 17990,
+          dailyPriceCents: 34,
+          currency: "USD",
+          promotionType: "commercial_seven_discount",
+          commercialOfferId: "offer-1",
+          commercialDiscountPercent: 30,
+        },
+      ],
+    });
+
+    expect(response.commercialOffer?.commercialOfferId).toBe("offer-1");
+    expect(response.plans[0]).toMatchObject({
+      planId: "vip_annual",
+      commercialOfferId: "offer-1",
+      commercialDiscountPercent: 30,
+    });
+  });
 });
 
 describe("GiftProductsResponse", () => {

src/data/schemas/payment/index.ts

@@ -8,6 +8,7 @@ export * from "./gift_product";
 export * from "./request/create_payment_order_request";
 export * from "./request/tip_message_request";
 export * from "./response/create_payment_order_response";
+export * from "./response/commercial_offer_response";
 export * from "./response/gift_products_response";
 export * from "./response/payment_order_status_response";
 export * from "./response/payment_plans_response";

src/data/schemas/payment/payment_plan.ts

@@ -25,6 +25,8 @@ export const PaymentPlanSchema = z
     mostPopular: booleanOrFalse,
     firstRechargeDiscountPercent: numberOrNull,
     promotionType: stringOrNull,
+    commercialOfferId: stringOrNull,
+    commercialDiscountPercent: numberOrNull,
   })
   .readonly();
 

src/data/schemas/payment/request/create_payment_order_request.ts

@@ -11,6 +11,7 @@ export const CreatePaymentOrderRequestSchema = z
     payChannel: PayChannelSchema,
     autoRenew: z.boolean(),
     recipientCharacterId: z.string().min(1).optional(),
+    commercialOfferId: z.string().min(1).optional(),
   })
   .readonly();
 

src/data/schemas/payment/response/commercial_offer_response.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+export const CommercialOfferResponseSchema = z
+  .object({
+    commercialOfferId: z.string().min(1),
+    planId: z.string().min(1),
+    subscriptionType: z.enum(["vip", "topup"]),
+    discountPercent: z.number().int().min(0).max(100),
+    pricePercent: z.number().int().min(0).max(100),
+    expiresAt: z.string().min(1),
+    message: z.string().min(1),
+    promotionType: z.string().min(1),
+  })
+  .readonly();
+
+export type CommercialOfferResponse = z.output<
+  typeof CommercialOfferResponseSchema
+>;

src/data/schemas/payment/response/index.ts

@@ -3,6 +3,7 @@
  */
 
 export * from "./create_payment_order_response";
+export * from "./commercial_offer_response";
 export * from "./gift_products_response";
 export * from "./payment_order_status_response";
 export * from "./payment_plans_response";

src/data/schemas/payment/response/payment_plans_response.ts

@@ -20,10 +20,24 @@ export const FirstRechargeOfferSchema = z
   })
   .readonly();
 
+export const CommercialOfferSummarySchema = z
+  .object({
+    enabled: booleanOrFalse,
+    commercialOfferId: z.string().min(1),
+    planId: z.string().min(1),
+    discountPercent: numberOrZero,
+    pricePercent: numberOrZero,
+    expiresAt: z.string().min(1),
+    triggerReason: stringOrEmpty,
+    message: stringOrEmpty,
+  })
+  .readonly();
+
 export const PaymentPlansResponseSchema = z
   .object({
     isFirstRecharge: booleanOrFalse,
     firstRechargeOffer: schemaOrNull(FirstRechargeOfferSchema),
+    commercialOffer: schemaOrNull(CommercialOfferSummarySchema),
     plans: arrayOrEmpty(PaymentPlanSchema),
   })
   .readonly();
@@ -35,7 +49,9 @@ export type PaymentPlansResponseData = z.output<
   typeof PaymentPlansResponseSchema
 >;
 export type FirstRechargeOfferData = z.output<typeof FirstRechargeOfferSchema>;
+export type CommercialOfferSummaryData = z.output<typeof CommercialOfferSummarySchema>;
 
 export type FirstRechargeOffer = FirstRechargeOfferData;
+export type CommercialOfferSummary = CommercialOfferSummaryData;
 
 export type PaymentPlansResponse = PaymentPlansResponseData;

src/data/services/api/__tests__/api_path.test.ts

@@ -6,7 +6,7 @@ import { ApiPath } from "../api_path";
 describe("ApiPath contract source", () => {
   it("uses the shared contract path for every static operation", () => {
     const staticOperations = Object.entries(apiContract).filter(
-      ([operationId]) => operationId !== "privateZoneAlbumUnlock",
+      ([, operation]) => !operation.path.includes("{"),
     );
 
     for (const [operationId, operation] of staticOperations) {
@@ -21,4 +21,10 @@ describe("ApiPath contract source", () => {
       "/api/private-zone/albums/album%2Fid%201/unlock",
     );
   });
+
+  it("fills and encodes the commercial offer path parameter", () => {
+    expect(ApiPath.paymentCommercialOfferAccept("offer/id 1")).toBe(
+      "/api/payment/commercial-offers/offer%2Fid%201/accept",
+    );
+  });
 });

src/data/services/api/__tests__/payment_api.test.ts

@@ -81,4 +81,38 @@ describe("PaymentApi", () => {
     });
     expect(response.message).toBe("Thank you for the thoughtful gift.");
   });
+
+  it("accepts a server-issued offer before opening the subscription page", async () => {
+    httpClientMock.mockResolvedValue({
+      success: true,
+      data: {
+        commercialOfferId: "offer-1",
+        planId: "vip_annual",
+        subscriptionType: "vip",
+        discountPercent: 30,
+        pricePercent: 70,
+        expiresAt: "2026-07-24T08:00:00+00:00",
+        message: "I got it for you.",
+        promotionType: "commercial_seven_discount",
+      },
+    });
+
+    const response = await new PaymentApi().acceptCommercialOffer("offer-1");
+
+    expect(httpClientMock).toHaveBeenCalledWith(
+      "/api/payment/commercial-offers/offer-1/accept",
+      { method: "POST" },
+    );
+    expect(response.discountPercent).toBe(30);
+  });
+
+  it("requests an offer-scoped plan catalog without changing the public call", async () => {
+    httpClientMock.mockResolvedValue({ success: true, data: { plans: [] } });
+
+    await new PaymentApi().getPlans("offer-1");
+
+    expect(httpClientMock).toHaveBeenCalledWith("/api/payment/plans", {
+      query: { commercialOfferId: "offer-1" },
+    });
+  });
 });

src/data/services/api/api_contract.json

@@ -17,6 +17,7 @@
   "paymentPlans": { "method": "get", "path": "/api/payment/plans" },
   "paymentGiftProducts": { "method": "get", "path": "/api/payment/gift-products" },
   "paymentTipMessage": { "method": "post", "path": "/api/payment/tip-message" },
+  "paymentCommercialOfferAccept": { "method": "post", "path": "/api/payment/commercial-offers/{offerId}/accept" },
   "chatSend": { "method": "post", "path": "/api/chat/send" },
   "chatOpeningMessage": { "method": "post", "path": "/api/chat/opening-message" },
   "chatHistory": { "method": "get", "path": "/api/chat/history" },

src/data/services/api/api_path.ts

@@ -66,6 +66,14 @@ export class ApiPath {
   /** 获取已支付礼物订单的角色感谢文案 */
   static readonly paymentTipMessage = apiContract.paymentTipMessage.path;
 
+  /** 接受角色发放的用户专属优惠 */
+  static paymentCommercialOfferAccept(offerId: string): string {
+    return apiContract.paymentCommercialOfferAccept.path.replace(
+      "{offerId}",
+      encodeURIComponent(offerId),
+    );
+  }
+
   // ============ 聊天相关 ============
   /** 发送消息 */
   static readonly chatSend = apiContract.chatSend.path;

src/data/services/api/payment_api.ts

@@ -7,6 +7,8 @@ import {
   CreatePaymentOrderRequest,
   CreatePaymentOrderResponse,
   CreatePaymentOrderResponseSchema,
+  CommercialOfferResponse,
+  CommercialOfferResponseSchema,
   GiftProductsResponse,
   GiftProductsResponseSchema,
   PaymentOrderStatusResponse,
@@ -24,13 +26,26 @@ import { ApiEnvelope, unwrap } from "./response_helper";
 
 export class PaymentApi {
   /** 获取 VIP 与 Top-up 套餐列表。 */
-  async getPlans(): Promise<PaymentPlansResponse> {
-    const env = await httpClient<ApiEnvelope<unknown>>(ApiPath.paymentPlans);
+  async getPlans(commercialOfferId?: string): Promise<PaymentPlansResponse> {
+    const env = await httpClient<ApiEnvelope<unknown>>(ApiPath.paymentPlans, {
+      ...(commercialOfferId ? { query: { commercialOfferId } } : {}),
+    });
     return PaymentPlansResponseSchema.parse(
       unwrap(env) as Record<string, unknown>,
     );
   }
 
+  /** 用户确认后激活一份后端签发的专属优惠。 */
+  async acceptCommercialOffer(offerId: string): Promise<CommercialOfferResponse> {
+    const env = await httpClient<ApiEnvelope<unknown>>(
+      ApiPath.paymentCommercialOfferAccept(offerId),
+      { method: "POST" },
+    );
+    return CommercialOfferResponseSchema.parse(
+      unwrap(env) as Record<string, unknown>,
+    );
+  }
+
   /** 一次获取当前角色的完整礼物目录。 */
   async getGiftProducts(characterId: string): Promise<GiftProductsResponse> {
     const env = await httpClient<ApiEnvelope<unknown>>(