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

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>>(