docs(M08-A): 记录权益余额抵扣提交状态

README.md

@@ -121,8 +121,8 @@ WSL 已验证：EMQX `5.8.9`、MQTTX CLI `1.13.0`、EMQX 服务 `active (running
 项目已开发部分模块。具体完成度不得从 README 猜测，必须以现有代码、测试、数据库迁移、Git 历史以及 `docs/current-baseline.md`、`docs/module-status.md`、`docs/feature-status.md` 为准。
 
 - 当前执行游标：`M08-A`（PARTIAL）
-- 最近工程提交：`53f5d67`，完成顾客端充值微信支付调起、通知验签解密和充值入账链路。
+- 最近工程提交：`dda2b3c`，完成顾客端优惠券、套餐和余额下单抵扣工程闭环。
-- 下一工程目标：继续 M08-A，补余额/优惠券/套餐下单抵扣集成。
+- 下一工程目标：继续 M08-A，补权益可视化选择器、真机合法域名、真实微信支付和实物开门验证。
 
 ## 版本递进
 

backend/src/orders/order-state-repository.ts

@@ -1,6 +1,7 @@
 import type { PoolConnection, ResultSetHeader, RowDataPacket } from 'mysql2/promise';
 import type { AccessProfile } from '../auth/rbac-repository.js';
 import type { MySqlPool } from '../db/mysql.js';
+import type { MarketingBenefitService } from '../wallets/marketing-benefit-service.js';
 
 export const orderActions = [
   'SUBMIT', 'CONFIRM_PAYMENT', 'RESERVE', 'START', 'FINISH', 'CANCEL',
@@ -71,7 +72,10 @@ export class OrderStateError extends Error {
 }
 
 export class OrderStateRepository {
-  constructor(private readonly pool: MySqlPool) {}
+  constructor(
+    private readonly pool: MySqlPool,
+    private readonly benefits?: Pick<MarketingBenefitService, 'releaseReservedInTransaction'>
+  ) {}
 
   async transition(actor: OrderActor, orderId: string, action: OrderAction, reason = '') {
     return this.transaction(async (connection) => {
@@ -223,6 +227,21 @@ export class OrderStateRepository {
          WHERE tenant_id = ? AND order_id = ?`,
         [tenantId, orderId]
       );
+      if (this.benefits) {
+        const [users] = await connection.execute<RowDataPacket[]>(
+          `SELECT user_id AS userId FROM qipai_order_user_access
+           WHERE tenant_id = ? AND order_id = ? ORDER BY id LIMIT 1`,
+          [tenantId, orderId]
+        );
+        if (users[0]?.userId) {
+          await this.benefits.releaseReservedInTransaction(connection, {
+            tenantId,
+            userId: String(users[0].userId),
+            orderId,
+            traceId: `order-benefit-release-${orderId}`
+          });
+        }
+      }
     }
   }
 

backend/src/orders/pricing-repository.ts

@@ -1,6 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import type { PoolConnection, ResultSetHeader, RowDataPacket } from 'mysql2/promise';
 import type { MySqlPool } from '../db/mysql.js';
+import type { MarketingBenefitService } from '../wallets/marketing-benefit-service.js';
 
 export type PricingMode = 'HOURLY' | 'OVERNIGHT' | 'FULL_DAY';
 
@@ -18,6 +19,14 @@ export interface QuoteInput {
   adjustment?: PricingAdjustment;
 }
 
+export interface OrderBenefitInput {
+  couponGrantId?: string | null;
+  packageHoldingId?: string | null;
+  packageMinutes?: number;
+  packageCreditCents?: number;
+  clientRequestId?: string;
+}
+
 interface RoomPricingRow extends RowDataPacket {
   id: string;
   storeId: string;
@@ -33,6 +42,7 @@ interface RoomPricingRow extends RowDataPacket {
   depositCents: number;
   minimumMinutes: number;
   maxAdvanceDays: number;
+  roomCategoryId: string | null;
 }
 interface CountRow extends RowDataPacket { total: number }
 
@@ -41,7 +51,10 @@ export class PricingError extends Error {
 }
 
 export class PricingRepository {
-  constructor(private readonly pool: MySqlPool) {}
+  constructor(
+    private readonly pool: MySqlPool,
+    private readonly benefits?: Pick<MarketingBenefitService, 'reserveForOrderInTransaction'>
+  ) {}
 
   async quote(input: QuoteInput) {
     const room = await this.loadRoom(this.pool, input.tenantId, input.roomId);
@@ -55,6 +68,7 @@ export class PricingRepository {
     userId: string;
     holdMinutes?: number;
     allowedStoreIds?: string[] | null;
+    benefits?: OrderBenefitInput | null;
   }) {
     return this.transaction(async (connection) => {
       const room = await this.loadRoom(connection, input.tenantId, input.roomId, true);
@@ -66,7 +80,7 @@ export class PricingRepository {
       const isHoliday = await this.isHoliday(
         connection, input.tenantId, input.startAt, room.timezone
       );
-      const quote = this.calculate(room, input, isHoliday);
+      let quote = this.calculate(room, input, isHoliday);
       const holdMinutes = Math.min(Math.max(input.holdMinutes ?? 15, 5), 30);
       const orderNo = `QP${Date.now()}${randomBytes(4).toString('hex').toUpperCase()}`;
       const [orderResult] = await connection.execute<ResultSetHeader>(
@@ -79,6 +93,43 @@ export class PricingRepository {
           holdMinutes, quote.totalCents]
       );
       const orderId = String(orderResult.insertId);
+      let benefitReservation = null;
+      const requestedBenefits = input.benefits;
+      if (this.benefits && requestedBenefits
+        && (requestedBenefits.couponGrantId || requestedBenefits.packageHoldingId)) {
+        if (!requestedBenefits.clientRequestId) {
+          throw new PricingError('BENEFIT_CLIENT_REQUEST_ID_REQUIRED');
+        }
+        benefitReservation = await this.benefits.reserveForOrderInTransaction(connection, {
+          tenantId: input.tenantId,
+          userId: input.userId,
+          orderId,
+          storeId: String(room.storeId),
+          roomId: input.roomId,
+          roomCategoryId: room.roomCategoryId,
+          orderAmountCents: quote.totalCents,
+          orderStartAt: input.startAt,
+          isHoliday,
+          couponGrantId: requestedBenefits.couponGrantId ?? null,
+          packageHoldingId: requestedBenefits.packageHoldingId ?? null,
+          packageMinutes: requestedBenefits.packageMinutes,
+          packageCreditCents: requestedBenefits.packageCreditCents,
+          clientRequestId: requestedBenefits.clientRequestId,
+          traceId: requestedBenefits.clientRequestId
+        });
+        quote = this.calculate(room, {
+          ...input,
+          adjustment: {
+            discountCents: benefitReservation.discountCents,
+            packageCreditCents: benefitReservation.packageCreditCents
+          }
+        }, isHoliday);
+        await connection.execute(
+          `UPDATE qipai_orders SET total_amount_cents = ?
+           WHERE tenant_id = ? AND id = ?`,
+          [quote.totalCents, input.tenantId, orderId]
+        );
+      }
       await connection.execute(
         `INSERT INTO qipai_order_price_snapshots
           (tenant_id, order_id, pricing_mode, duration_minutes, unit_price_cents,
@@ -115,7 +166,8 @@ export class PricingRepository {
         storeId: String(room.storeId),
         reservationId: String(reservationResult.insertId),
         holdMinutes,
-        quote
+        quote,
+        benefitReservation
       };
     });
   }
@@ -250,7 +302,8 @@ export class PricingRepository {
               r.minimum_spend_cents AS minimumSpendCents,
               r.deposit_cents AS depositCents,
               r.minimum_minutes AS minimumMinutes,
-              r.max_advance_days AS maxAdvanceDays
+              r.max_advance_days AS maxAdvanceDays,
+              r.room_category_id AS roomCategoryId
        FROM qipai_rooms r
        INNER JOIN qipai_stores s
          ON s.id = r.store_id AND s.tenant_id = r.tenant_id AND s.deleted_at IS NULL

backend/src/payments/payment-repository.ts

@@ -1,6 +1,8 @@
 import { randomBytes } from 'node:crypto';
 import type { PoolConnection, ResultSetHeader, RowDataPacket } from 'mysql2/promise';
 import type { MySqlPool } from '../db/mysql.js';
+import type { MarketingBenefitService } from '../wallets/marketing-benefit-service.js';
+import type { WalletLedgerService } from '../wallets/wallet-ledger-service.js';
 
 export type PaymentProvider = 'WECHAT' | 'BALANCE' | 'PACKAGE' | 'GROUP_BUY' | 'TEST';
 
@@ -31,7 +33,11 @@ export class PaymentError extends Error {
 }
 
 export class PaymentRepository {
-  constructor(private readonly pool: MySqlPool) {}
+  constructor(
+    private readonly pool: MySqlPool,
+    private readonly wallet?: Pick<WalletLedgerService, 'debitInTransaction'>,
+    private readonly benefits?: Pick<MarketingBenefitService, 'confirmReservedInTransaction'>
+  ) {}
 
   async createPayment(input: {
     tenantId: string;
@@ -54,7 +60,7 @@ export class PaymentRepository {
       if (input.provider === 'TEST' && !input.testAdapterEnabled) {
         throw new PaymentError('TEST_PAYMENT_DISABLED');
       }
-      if (input.provider !== 'TEST') {
+      if (!['TEST', 'BALANCE'].includes(input.provider)) {
         await this.resolveConfig(
           connection, input.tenantId, input.platformAppId, order.storeId, input.provider
         );
@@ -94,6 +100,36 @@ export class PaymentRepository {
         [input.tenantId, paymentId, input.provider, amountCents,
           input.provider === 'TEST' ? 'test' : 'configured']
       );
+      if (input.provider === 'BALANCE') {
+        if (!this.wallet) throw new PaymentError('WALLET_SETTLEMENT_NOT_CONFIGURED');
+        await this.wallet.debitInTransaction(connection, {
+          tenantId: input.tenantId,
+          userId: input.userId,
+          scopeType: 'STORE',
+          storeId: order.storeId,
+          businessType: 'ORDER_PAYMENT',
+          businessId: input.orderId,
+          entryType: 'CONSUME',
+          amountCents,
+          traceId: input.clientRequestId,
+          note: 'Customer balance payment',
+          metadata: { paymentId, provider: input.provider }
+        });
+        await this.applyPaymentSuccess(connection, {
+          paymentId,
+          orderId: input.orderId,
+          tenantId: input.tenantId,
+          userId: input.userId,
+          amountCents,
+          providerPaymentId: `BAL-${paymentNo}`,
+          traceId: input.clientRequestId,
+          reason: 'Balance payment completed'
+        });
+        return this.paymentResponse({
+          id: paymentId, orderId: input.orderId, paymentNo, provider: input.provider,
+          status: 'SUCCEEDED', amountCents
+        } as PaymentRow, false, input.testAdapterEnabled);
+      }
       return this.paymentResponse({
         id: paymentId, orderId: input.orderId, paymentNo, provider: input.provider,
         status: 'PENDING', amountCents
@@ -150,45 +186,16 @@ export class PaymentRepository {
         );
         return { paymentId: input.paymentId, status: 'SUCCEEDED', idempotent: true };
       }
-      await connection.execute(
+      await this.applyPaymentSuccess(connection, {
-        `UPDATE qipai_payments
+        paymentId: input.paymentId,
-         SET status = 'SUCCEEDED', provider_payment_id = ?,
+        orderId: payment.orderId,
-             paid_at = UTC_TIMESTAMP(3), raw_notify = JSON_OBJECT('verified', TRUE)
+        tenantId: input.tenantId,
-         WHERE tenant_id = ? AND id = ? AND status = 'PENDING'`,
+        userId: input.userId,
-        [`TEST-${input.callbackId}`, input.tenantId, input.paymentId]
+        amountCents: Number(payment.amountCents),
-      );
+        providerPaymentId: `TEST-${input.callbackId}`,
-      await connection.execute(
+        traceId: input.traceId,
-        `UPDATE qipai_orders
+        reason: 'Verified payment callback'
-         SET paid_amount_cents = paid_amount_cents + ?
+      });
-         WHERE tenant_id = ? AND id = ?`,
-        [payment.amountCents, input.tenantId, payment.orderId]
-      );
-      const order = await this.loadOrder(connection, input.tenantId, payment.orderId, true);
-      if (Number(order.paidAmountCents) >= Number(order.totalAmountCents)
-        && order.status === 'PENDING_PAYMENT') {
-        const nextVersion = Number((order as OrderRow & { statusVersion?: number }).statusVersion ?? 1) + 1;
-        await connection.execute(
-          `UPDATE qipai_orders SET status = 'PAID', status_version = ?,
-             status_updated_at = UTC_TIMESTAMP(3)
-           WHERE tenant_id = ? AND id = ?`,
-          [nextVersion, input.tenantId, payment.orderId]
-        );
-        await connection.execute(
-          `UPDATE qipai_room_reservations
-           SET status = 'CONSUMED', expires_at = GREATEST(expires_at, ends_at)
-           WHERE tenant_id = ? AND order_id = ? AND status = 'HELD'`,
-          [input.tenantId, payment.orderId]
-        );
-        await connection.execute(
-          `INSERT INTO qipai_order_status_history
-            (tenant_id, order_id, from_status, to_status, action, actor_type,
-             actor_id, source, reason, trace_id, metadata)
-           VALUES (?, ?, 'PENDING_PAYMENT', 'PAID', 'CONFIRM_PAYMENT', 'SYSTEM',
-             NULL, 'PAYMENT', 'Verified payment callback', ?,
-             JSON_OBJECT('statusVersion', ?, 'paymentId', ?))`,
-          [input.tenantId, payment.orderId, input.traceId, nextVersion, input.paymentId]
-        );
-      }
       await connection.execute(
         `UPDATE qipai_payment_callbacks
          SET processing_status = 'PROCESSED', processed_at = UTC_TIMESTAMP(3)
@@ -288,6 +295,67 @@ export class PaymentRepository {
     if (!rows[0]) throw new PaymentError('ORDER_ACCESS_FORBIDDEN');
   }
 
+  async applyPaymentSuccess(
+    connection: PoolConnection,
+    input: {
+      paymentId: string;
+      orderId: string;
+      tenantId: string;
+      userId?: string;
+      amountCents: number;
+      providerPaymentId: string;
+      traceId: string;
+      reason: string;
+    }
+  ) {
+    await connection.execute(
+      `UPDATE qipai_payments
+       SET status = 'SUCCEEDED', provider_payment_id = ?,
+           paid_at = UTC_TIMESTAMP(3), raw_notify = JSON_OBJECT('verified', TRUE)
+       WHERE tenant_id = ? AND id = ? AND status = 'PENDING'`,
+      [input.providerPaymentId, input.tenantId, input.paymentId]
+    );
+    await connection.execute(
+      `UPDATE qipai_orders
+       SET paid_amount_cents = paid_amount_cents + ?
+       WHERE tenant_id = ? AND id = ?`,
+      [input.amountCents, input.tenantId, input.orderId]
+    );
+    const order = await this.loadOrder(connection, input.tenantId, input.orderId, true);
+    if (Number(order.paidAmountCents) >= Number(order.totalAmountCents)
+      && order.status === 'PENDING_PAYMENT') {
+      if (this.benefits && input.userId) {
+        await this.benefits.confirmReservedInTransaction(connection, {
+          tenantId: input.tenantId,
+          userId: input.userId,
+          orderId: input.orderId,
+          traceId: input.traceId
+        });
+      }
+      const nextVersion = Number((order as OrderRow & { statusVersion?: number }).statusVersion ?? 1) + 1;
+      await connection.execute(
+        `UPDATE qipai_orders SET status = 'PAID', status_version = ?,
+           status_updated_at = UTC_TIMESTAMP(3)
+         WHERE tenant_id = ? AND id = ?`,
+        [nextVersion, input.tenantId, input.orderId]
+      );
+      await connection.execute(
+        `UPDATE qipai_room_reservations
+         SET status = 'CONSUMED', expires_at = GREATEST(expires_at, ends_at)
+         WHERE tenant_id = ? AND order_id = ? AND status = 'HELD'`,
+        [input.tenantId, input.orderId]
+      );
+      await connection.execute(
+        `INSERT INTO qipai_order_status_history
+          (tenant_id, order_id, from_status, to_status, action, actor_type,
+           actor_id, source, reason, trace_id, metadata)
+         VALUES (?, ?, 'PENDING_PAYMENT', 'PAID', 'CONFIRM_PAYMENT', 'SYSTEM',
+           NULL, 'PAYMENT', ?, ?, JSON_OBJECT('statusVersion', ?, 'paymentId', ?))`,
+        [input.tenantId, input.orderId, input.reason, input.traceId, nextVersion, input.paymentId]
+      );
+    }
+  }
+
   private async transaction<T>(work: (connection: PoolConnection) => Promise<T>) {
     const connection = await this.pool.getConnection();
     try {

backend/src/payments/wechat-payment-service.ts

@@ -19,6 +19,7 @@ interface PaymentRow extends RowDataPacket {
   paidAmountCents: number;
   totalAmountCents: number;
   orderStatus: string;
+  userId?: string;
 }
 
 interface RefundRow extends RowDataPacket {
@@ -419,44 +420,17 @@ export class WechatPaymentService {
       );
       return;
     }
-    await connection.execute(
+    const userId = await this.loadOrderUserId(connection, payment.tenantId, payment.orderId);
-      `UPDATE qipai_payments
+    await this.paymentRepository.applyPaymentSuccess(connection, {
-       SET status = 'SUCCEEDED', provider_payment_id = ?,
+      paymentId: payment.id,
-           paid_at = UTC_TIMESTAMP(3), raw_notify = JSON_OBJECT('verified', TRUE)
+      orderId: payment.orderId,
-       WHERE tenant_id = ? AND id = ? AND status = 'PENDING'`,
+      tenantId: payment.tenantId,
-      [transactionId, payment.tenantId, payment.id]
+      userId,
-    );
+      amountCents: Number(payment.amountCents),
-    await connection.execute(
+      providerPaymentId: transactionId,
-      `UPDATE qipai_orders SET paid_amount_cents = paid_amount_cents + ?
+      traceId,
-       WHERE tenant_id = ? AND id = ?`,
+      reason: 'Verified Wechat payment callback'
-      [payment.amountCents, payment.tenantId, payment.orderId]
+    });
-    );
-    const nextPaid = Number(payment.paidAmountCents) + Number(payment.amountCents);
-    if (nextPaid >= Number(payment.totalAmountCents)
-      && payment.orderStatus === 'PENDING_PAYMENT') {
-      await connection.execute(
-        `UPDATE qipai_orders
-         SET status = 'PAID', status_version = status_version + 1,
-             status_updated_at = UTC_TIMESTAMP(3)
-         WHERE tenant_id = ? AND id = ?`,
-        [payment.tenantId, payment.orderId]
-      );
-      await connection.execute(
-        `UPDATE qipai_room_reservations
-         SET status = 'CONSUMED', expires_at = GREATEST(expires_at, ends_at)
-         WHERE tenant_id = ? AND order_id = ? AND status = 'HELD'`,
-        [payment.tenantId, payment.orderId]
-      );
-      await connection.execute(
-        `INSERT INTO qipai_order_status_history
-          (tenant_id, order_id, from_status, to_status, action, actor_type,
-           actor_id, source, reason, trace_id, metadata)
-         VALUES (?, ?, 'PENDING_PAYMENT', 'PAID', 'CONFIRM_PAYMENT', 'SYSTEM',
-           NULL, 'PAYMENT', 'Verified Wechat payment callback', ?,
-           JSON_OBJECT('paymentId', ?))`,
-        [payment.tenantId, payment.orderId, traceId, payment.id]
-      );
-    }
     await connection.execute(
       `UPDATE qipai_payment_callbacks
        SET processing_status = 'PROCESSED', processed_at = UTC_TIMESTAMP(3)
@@ -465,6 +439,16 @@ export class WechatPaymentService {
     );
   }
 
+  private async loadOrderUserId(connection: PoolConnection, tenantId: string, orderId: string) {
+    const [rows] = await connection.execute<RowDataPacket[]>(
+      `SELECT user_id AS userId FROM qipai_order_user_access
+       WHERE tenant_id = ? AND order_id = ? AND revoked_at IS NULL
+       ORDER BY id LIMIT 1`,
+      [tenantId, orderId]
+    );
+    return rows[0]?.userId ? String(rows[0].userId) : undefined;
+  }
+
   private async rejectCallback(
     connection: PoolConnection, tenantId: string, callbackId: string, code: string
   ) {

backend/src/routes/pricing.ts

@@ -9,7 +9,14 @@ const requestSchema = z.object({
   roomId: z.string().regex(/^[1-9]\d{0,19}$/),
   startAt: z.coerce.date(),
   endAt: z.coerce.date(),
-  pricingMode: z.enum(['HOURLY', 'OVERNIGHT', 'FULL_DAY']).default('HOURLY')
+  pricingMode: z.enum(['HOURLY', 'OVERNIGHT', 'FULL_DAY']).default('HOURLY'),
+  benefits: z.object({
+    couponGrantId: z.string().regex(/^[1-9]\d{0,19}$/).nullable().optional(),
+    packageHoldingId: z.string().regex(/^[1-9]\d{0,19}$/).nullable().optional(),
+    packageMinutes: z.number().int().min(0).optional(),
+    packageCreditCents: z.number().int().min(0).optional(),
+    clientRequestId: z.string().min(8).max(128)
+  }).strict().optional()
 }).refine((value) => value.endAt > value.startAt);
 const adminReserveSchema = requestSchema.and(z.object({
   userId: z.string().regex(/^[1-9]\d{0,19}$/)

backend/src/server.ts

@@ -36,14 +36,16 @@ import { DeviceControlService } from './devices/device-control-service.js';
 import { MemberProfileService } from './wallets/member-profile-service.js';
 import { RechargeService } from './wallets/recharge-service.js';
 import { WalletLedgerService } from './wallets/wallet-ledger-service.js';
+import { MarketingBenefitService } from './wallets/marketing-benefit-service.js';
 
 const config = loadConfig();
 const pool = createMySqlPool(config);
 const authRepository = new AuthRepository(pool);
 const accessControl = new RbacRepository(pool);
 const orderManagementRepository = new OrderManagementRepository(pool);
-const paymentRepository = new PaymentRepository(pool);
 const walletLedgerService = new WalletLedgerService(pool);
+const marketingBenefits = new MarketingBenefitService(pool);
+const paymentRepository = new PaymentRepository(pool, walletLedgerService, marketingBenefits);
 const wechatCredentials = parseWechatPayCredentials(config.payment.wechatCredentialsJson);
 const wechatPayClient = new WechatPayClient(new FetchWechatPayTransport());
 const thirdPartyCredentials = parseThirdPartyCredentials(config.thirdParty.credentialsJson);
@@ -94,13 +96,13 @@ const app = await buildApp({
     jwtSecret: config.auth.jwtSecret
   },
   pricing: {
-    repository: new PricingRepository(pool),
+    repository: new PricingRepository(pool, marketingBenefits),
     authRepository,
     accessControl,
     jwtSecret: config.auth.jwtSecret
   },
   orderState: {
-    repository: new OrderStateRepository(pool),
+    repository: new OrderStateRepository(pool, marketingBenefits),
     authRepository,
     accessControl,
     jwtSecret: config.auth.jwtSecret,

backend/src/wallets/marketing-benefit-service.ts

@@ -67,72 +67,79 @@ export class MarketingBenefitService {
     traceId: string;
   }) {
     return this.transaction(async (connection) => {
-      const duplicate = await this.findUsageByRequest(connection, input);
+      return this.reserveForOrderInTransaction(connection, input);
-      if (duplicate.length > 0) return reserveResponse(duplicate, true);
-
-      const usages: UsageRow[] = [];
-      if (input.couponGrantId) {
-        const coupon = await this.loadCoupon(connection, input, input.couponGrantId);
-        assertUsableBenefit(coupon, input, 'COUPON');
-        const discountCents = coupon.couponType === 'FULL_REDUCTION'
-          ? Math.min(Number(coupon.discountAmountCents), input.orderAmountCents)
-          : 0;
-        const minutes = coupon.couponType === 'TIME' ? Number(coupon.timeMinutes) : 0;
-        const usage = await this.insertUsage(connection, {
-          ...input,
-          benefitType: 'COUPON',
-          benefitId: coupon.id,
-          discountCents,
-          packageCreditCents: 0,
-          minutes
-        });
-        await connection.execute(
-          `UPDATE qipai_coupon_grants
-           SET status = 'FROZEN', frozen_order_id = ?
-           WHERE tenant_id = ? AND id = ?`,
-          [input.orderId, input.tenantId, coupon.id]
-        );
-        usages.push(usage);
-      }
-
-      if (input.packageHoldingId) {
-        const holding = await this.loadPackageHolding(connection, input, input.packageHoldingId);
-        assertUsableBenefit(holding, input, 'PACKAGE');
-        const packageCreditCents = input.packageCreditCents ?? 0;
-        const minutes = input.packageMinutes ?? 0;
-        if (minutes <= 0 && packageCreditCents <= 0) {
-          throw new MarketingBenefitError('BENEFIT_PACKAGE_USAGE_EMPTY');
-        }
-        if (minutes > Number(holding.remainingMinutes)) {
-          throw new MarketingBenefitError('BENEFIT_PACKAGE_MINUTES_INSUFFICIENT');
-        }
-        if (packageCreditCents > Number(holding.remainingAmountCents)) {
-          throw new MarketingBenefitError('BENEFIT_PACKAGE_AMOUNT_INSUFFICIENT');
-        }
-        const usage = await this.insertUsage(connection, {
-          ...input,
-          benefitType: 'PACKAGE',
-          benefitId: holding.id,
-          discountCents: 0,
-          packageCreditCents,
-          minutes
-        });
-        await connection.execute(
-          `UPDATE qipai_package_holdings
-           SET status = 'FROZEN', frozen_order_id = ?
-           WHERE tenant_id = ? AND id = ?`,
-          [input.orderId, input.tenantId, holding.id]
-        );
-        usages.push(usage);
-      }
-
-      if (usages.length === 0) {
-        throw new MarketingBenefitError('BENEFIT_EMPTY');
-      }
-      return reserveResponse(usages, false);
     });
   }
 
+  async reserveForOrderInTransaction(
+    connection: PoolConnection,
+    input: Parameters<MarketingBenefitService['reserveForOrder']>[0]
+  ) {
+    const duplicate = await this.findUsageByRequest(connection, input);
+    if (duplicate.length > 0) return reserveResponse(duplicate, true);
+
+    const usages: UsageRow[] = [];
+    if (input.couponGrantId) {
+      const coupon = await this.loadCoupon(connection, input, input.couponGrantId);
+      assertUsableBenefit(coupon, input, 'COUPON');
+      const discountCents = coupon.couponType === 'FULL_REDUCTION'
+        ? Math.min(Number(coupon.discountAmountCents), input.orderAmountCents)
+        : 0;
+      const minutes = coupon.couponType === 'TIME' ? Number(coupon.timeMinutes) : 0;
+      const usage = await this.insertUsage(connection, {
+        ...input,
+        benefitType: 'COUPON',
+        benefitId: coupon.id,
+        discountCents,
+        packageCreditCents: 0,
+        minutes
+      });
+      await connection.execute(
+        `UPDATE qipai_coupon_grants
+         SET status = 'FROZEN', frozen_order_id = ?
+         WHERE tenant_id = ? AND id = ?`,
+        [input.orderId, input.tenantId, coupon.id]
+      );
+      usages.push(usage);
+    }
+
+    if (input.packageHoldingId) {
+      const holding = await this.loadPackageHolding(connection, input, input.packageHoldingId);
+      assertUsableBenefit(holding, input, 'PACKAGE');
+      const packageCreditCents = input.packageCreditCents ?? 0;
+      const minutes = input.packageMinutes ?? 0;
+      if (minutes <= 0 && packageCreditCents <= 0) {
+        throw new MarketingBenefitError('BENEFIT_PACKAGE_USAGE_EMPTY');
+      }
+      if (minutes > Number(holding.remainingMinutes)) {
+        throw new MarketingBenefitError('BENEFIT_PACKAGE_MINUTES_INSUFFICIENT');
+      }
+      if (packageCreditCents > Number(holding.remainingAmountCents)) {
+        throw new MarketingBenefitError('BENEFIT_PACKAGE_AMOUNT_INSUFFICIENT');
+      }
+      const usage = await this.insertUsage(connection, {
+        ...input,
+        benefitType: 'PACKAGE',
+        benefitId: holding.id,
+        discountCents: 0,
+        packageCreditCents,
+        minutes
+      });
+      await connection.execute(
+        `UPDATE qipai_package_holdings
+         SET status = 'FROZEN', frozen_order_id = ?
+         WHERE tenant_id = ? AND id = ?`,
+        [input.orderId, input.tenantId, holding.id]
+      );
+      usages.push(usage);
+    }
+
+    if (usages.length === 0) {
+      throw new MarketingBenefitError('BENEFIT_EMPTY');
+    }
+    return reserveResponse(usages, false);
+  }
+
   async confirmReserved(input: {
     tenantId: string;
     userId: string;
@@ -140,50 +147,57 @@ export class MarketingBenefitService {
     traceId: string;
   }) {
     return this.transaction(async (connection) => {
-      const usages = await this.loadOrderUsages(connection, input, true);
+      return this.confirmReservedInTransaction(connection, input);
-      if (usages.length === 0) throw new MarketingBenefitError('BENEFIT_USAGE_NOT_FOUND');
-      if (usages.every((usage) => usage.status === 'CONFIRMED')) {
-        return reserveResponse(usages, true);
-      }
-      for (const usage of usages) {
-        if (usage.status !== 'FROZEN') {
-          throw new MarketingBenefitError('BENEFIT_USAGE_STATUS_INVALID');
-        }
-        if (usage.benefitType === 'COUPON') {
-          await connection.execute(
-            `UPDATE qipai_coupon_grants
-             SET status = CASE WHEN remaining_uses <= 1 THEN 'USED' ELSE 'AVAILABLE' END,
-                 remaining_uses = GREATEST(remaining_uses - 1, 0),
-                 used_count = used_count + 1,
-                 used_at = UTC_TIMESTAMP(3),
-                 frozen_order_id = NULL
-             WHERE tenant_id = ? AND id = ?`,
-            [input.tenantId, usage.benefitId]
-          );
-        } else {
-          await connection.execute(
-            `UPDATE qipai_package_holdings
-             SET remaining_minutes = GREATEST(remaining_minutes - ?, 0),
-                 remaining_amount_cents = GREATEST(remaining_amount_cents - ?, 0),
-                 status = CASE
-                   WHEN remaining_minutes <= ? AND remaining_amount_cents <= ? THEN 'EXHAUSTED'
-                   ELSE 'ACTIVE'
-                 END,
-                 frozen_order_id = NULL
-             WHERE tenant_id = ? AND id = ?`,
-            [
-              usage.minutes, usage.packageCreditCents,
-              usage.minutes, usage.packageCreditCents,
-              input.tenantId, usage.benefitId
-            ]
-          );
-        }
-        await this.updateUsageStatus(connection, input.tenantId, usage.id, 'CONFIRMED');
-      }
-      return reserveResponse(usages.map((usage) => ({ ...usage, status: 'CONFIRMED' })), false);
     });
   }
 
+  async confirmReservedInTransaction(
+    connection: PoolConnection,
+    input: Parameters<MarketingBenefitService['confirmReserved']>[0]
+  ) {
+    const usages = await this.loadOrderUsages(connection, input, true);
+    if (usages.length === 0) return reserveResponse([], true);
+    if (usages.every((usage) => usage.status === 'CONFIRMED')) {
+      return reserveResponse(usages, true);
+    }
+    for (const usage of usages) {
+      if (usage.status !== 'FROZEN') {
+        throw new MarketingBenefitError('BENEFIT_USAGE_STATUS_INVALID');
+      }
+      if (usage.benefitType === 'COUPON') {
+        await connection.execute(
+          `UPDATE qipai_coupon_grants
+           SET status = CASE WHEN remaining_uses <= 1 THEN 'USED' ELSE 'AVAILABLE' END,
+               remaining_uses = GREATEST(remaining_uses - 1, 0),
+               used_count = used_count + 1,
+               used_at = UTC_TIMESTAMP(3),
+               frozen_order_id = NULL
+           WHERE tenant_id = ? AND id = ?`,
+          [input.tenantId, usage.benefitId]
+        );
+      } else {
+        await connection.execute(
+          `UPDATE qipai_package_holdings
+           SET remaining_minutes = GREATEST(remaining_minutes - ?, 0),
+               remaining_amount_cents = GREATEST(remaining_amount_cents - ?, 0),
+               status = CASE
+                 WHEN remaining_minutes <= ? AND remaining_amount_cents <= ? THEN 'EXHAUSTED'
+                 ELSE 'ACTIVE'
+               END,
+               frozen_order_id = NULL
+           WHERE tenant_id = ? AND id = ?`,
+          [
+            usage.minutes, usage.packageCreditCents,
+            usage.minutes, usage.packageCreditCents,
+            input.tenantId, usage.benefitId
+          ]
+        );
+      }
+      await this.updateUsageStatus(connection, input.tenantId, usage.id, 'CONFIRMED');
+    }
+    return reserveResponse(usages.map((usage) => ({ ...usage, status: 'CONFIRMED' })), false);
+  }
+
   async releaseReserved(input: {
     tenantId: string;
     userId: string;
@@ -191,36 +205,43 @@ export class MarketingBenefitService {
     traceId: string;
   }) {
     return this.transaction(async (connection) => {
-      const usages = await this.loadOrderUsages(connection, input, true);
+      return this.releaseReservedInTransaction(connection, input);
-      if (usages.length === 0) throw new MarketingBenefitError('BENEFIT_USAGE_NOT_FOUND');
-      if (usages.every((usage) => usage.status === 'RELEASED')) {
-        return reserveResponse(usages, true);
-      }
-      for (const usage of usages) {
-        if (usage.status !== 'FROZEN') {
-          throw new MarketingBenefitError('BENEFIT_USAGE_STATUS_INVALID');
-        }
-        if (usage.benefitType === 'COUPON') {
-          await connection.execute(
-            `UPDATE qipai_coupon_grants
-             SET status = 'AVAILABLE', frozen_order_id = NULL
-             WHERE tenant_id = ? AND id = ?`,
-            [input.tenantId, usage.benefitId]
-          );
-        } else {
-          await connection.execute(
-            `UPDATE qipai_package_holdings
-             SET status = 'ACTIVE', frozen_order_id = NULL
-             WHERE tenant_id = ? AND id = ?`,
-            [input.tenantId, usage.benefitId]
-          );
-        }
-        await this.updateUsageStatus(connection, input.tenantId, usage.id, 'RELEASED');
-      }
-      return reserveResponse(usages.map((usage) => ({ ...usage, status: 'RELEASED' })), false);
     });
   }
 
+  async releaseReservedInTransaction(
+    connection: PoolConnection,
+    input: Parameters<MarketingBenefitService['releaseReserved']>[0]
+  ) {
+    const usages = await this.loadOrderUsages(connection, input, true);
+    if (usages.length === 0) return reserveResponse([], true);
+    if (usages.every((usage) => usage.status === 'RELEASED')) {
+      return reserveResponse(usages, true);
+    }
+    for (const usage of usages) {
+      if (usage.status !== 'FROZEN') continue;
+      if (usage.benefitType === 'COUPON') {
+        await connection.execute(
+          `UPDATE qipai_coupon_grants
+           SET status = 'AVAILABLE', frozen_order_id = NULL
+           WHERE tenant_id = ? AND id = ?`,
+          [input.tenantId, usage.benefitId]
+        );
+      } else {
+        await connection.execute(
+          `UPDATE qipai_package_holdings
+           SET status = 'ACTIVE', frozen_order_id = NULL
+           WHERE tenant_id = ? AND id = ?`,
+          [input.tenantId, usage.benefitId]
+        );
+      }
+      await this.updateUsageStatus(connection, input.tenantId, usage.id, 'RELEASED');
+    }
+    return reserveResponse(usages.map((usage) => (
+      usage.status === 'FROZEN' ? { ...usage, status: 'RELEASED' } : usage
+    )), false);
+  }
+
   private async loadCoupon(
     connection: PoolConnection,
     input: { tenantId: string; userId: string },

backend/src/wallets/wallet-ledger-service.ts

@@ -47,20 +47,27 @@ export class WalletLedgerService {
 
   async debit(input: WalletMutationInput & { amountCents: number }) {
     return this.transaction(async (connection) => {
-      const account = await this.ensureAccount(connection, input, true);
+      return this.debitInTransaction(connection, input);
-      const duplicate = await this.findDuplicate(connection, account, input);
-      if (duplicate) return ledgerResponse(account, duplicate, true);
-      const amount = nonNegative(input.amountCents, 'WALLET_DEBIT_AMOUNT_INVALID');
-      if (amount <= 0) throw new WalletLedgerError('WALLET_DEBIT_AMOUNT_INVALID');
-      const giftUsed = Math.min(Number(account.giftBalanceCents), amount);
-      const cashUsed = amount - giftUsed;
-      if (cashUsed > Number(account.cashBalanceCents)) {
-        throw new WalletLedgerError('WALLET_BALANCE_INSUFFICIENT');
-      }
-      return this.applyDelta(connection, account, input, -cashUsed, -giftUsed, false);
     });
   }
 
+  async debitInTransaction(
+    connection: PoolConnection,
+    input: WalletMutationInput & { amountCents: number }
+  ) {
+    const account = await this.ensureAccount(connection, input, true);
+    const duplicate = await this.findDuplicate(connection, account, input);
+    if (duplicate) return ledgerResponse(account, duplicate, true);
+    const amount = nonNegative(input.amountCents, 'WALLET_DEBIT_AMOUNT_INVALID');
+    if (amount <= 0) throw new WalletLedgerError('WALLET_DEBIT_AMOUNT_INVALID');
+    const giftUsed = Math.min(Number(account.giftBalanceCents), amount);
+    const cashUsed = amount - giftUsed;
+    if (cashUsed > Number(account.cashBalanceCents)) {
+      throw new WalletLedgerError('WALLET_BALANCE_INSUFFICIENT');
+    }
+    return this.applyDelta(connection, account, input, -cashUsed, -giftUsed, false);
+  }
+
   async adjust(input: WalletMutationInput & {
     cashDeltaCents?: number;
     giftDeltaCents?: number;

backend/tests/payment.test.mjs

@@ -76,6 +76,15 @@ assert.equal(created.statusCode, 201);
 assert.equal(createInput.platformAppId, '9');
 assert.equal('amountCents' in createInput, false);
 
+const balanceCreated = await app.inject({
+  method: 'POST',
+  url: '/app-api/payments',
+  headers: { authorization: `Bearer ${token}` },
+  payload: { orderId: '31', provider: 'BALANCE', clientRequestId: 'request-balance-0001' }
+});
+assert.equal(balanceCreated.statusCode, 201);
+assert.equal(createInput.provider, 'BALANCE');
+
 const completed = await app.inject({
   method: 'POST',
   url: '/app-api/payments/51/test-complete',

backend/tests/pricing.test.mjs

@@ -65,6 +65,13 @@ const reserved = await app.inject({
     startAt: startAt.toISOString(),
     endAt: endAt.toISOString(),
     pricingMode: 'HOURLY',
+    benefits: {
+      couponGrantId: '401',
+      packageHoldingId: '501',
+      packageMinutes: 60,
+      packageCreditCents: 2000,
+      clientRequestId: 'benefit-route-0001'
+    },
     totalCents: 1,
     discountCents: 999999
   }
@@ -74,6 +81,13 @@ assert.equal(reserveInput.tenantId, '7');
 assert.equal(reserveInput.userId, '21');
 assert.equal('totalCents' in reserveInput, false);
 assert.equal('discountCents' in reserveInput, false);
+assert.deepEqual(reserveInput.benefits, {
+  couponGrantId: '401',
+  packageHoldingId: '501',
+  packageMinutes: 60,
+  packageCreditCents: 2000,
+  clientRequestId: 'benefit-route-0001'
+});
 
 const unauthenticated = await app.inject({
   method: 'POST',

docs/api-changelog/2026-06-25-M08-A-recharge-wechat.md

@@ -9,3 +9,18 @@
   - 鉴权：微信支付平台证书签名和 AES-GCM 资源解密。
   - 行为：按 `out_trade_no` 定位充值单，校验金额，写入 `qipai_payment_callbacks` 幂等记录，成功后给钱包现金/赠送余额入账。
   - 隐私：通知 payload 入库前移除 `payer` 等敏感对象。
+
+## M08-A 权益与余额下单抵扣
+
+- `POST /app-api/orders/reserve`
+  - 新增可选 `benefits` 对象：`couponGrantId`、`packageHoldingId`、`packageMinutes`、`packageCreditCents`、`clientRequestId`。
+  - 行为：只接受权益 ID 和请求幂等号，不接受客户端自报总价；后端按报价、权益规则和剩余量重新计算 `discountCents`、`packageCreditCents` 与订单 `totalCents`。
+  - 返回：保留原订单预占结构，新增 `benefitReservation`，包含冻结状态、抵扣金额、套餐抵扣金额、分钟和使用记录。
+
+- `POST /app-api/payments`
+  - `provider` 继续支持 `WECHAT`、`TEST`，新增顾客端 `BALANCE` 实际扣款闭环。
+  - `BALANCE` 行为：按当前订单应付金额创建支付单，在同一事务内从门店钱包按赠送余额优先、现金余额补足扣款；成功后支付单状态为 `SUCCEEDED`，订单满足金额时推进为 `PAID` 并确认冻结权益。
+  - `WECHAT`/`TEST` 成功路径：支付通知或测试回调成功后统一确认冻结优惠券和套餐；重复通知保持幂等。
+
+- `POST /app-api/orders/:orderId/cancel`
+  - 行为补充：订单取消释放房间预占和访问权限时，同时释放仍处于 `FROZEN` 的优惠券和套餐持有记录。

docs/current-baseline.md

@@ -2,7 +2,7 @@
 
 > V5.0 首次核验日期：2026-06-16  
 > audited_commit: `4ae9296`
-> next_engineering_target: 继续 M08-A 余额/优惠券/套餐下单抵扣集成
+> next_engineering_target: 继续 M08-A 权益可视化选择器、真机合法域名、真实微信支付和实物开门验证
 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。
 
 ## 总体结论
@@ -13,7 +13,7 @@
 | Git 远端 | `origin=ssh://git@git.txyundm.cn:2222/panda/qipai.git`，分支 `main` | `git rev-list main...origin/main` 为 `0 0` | 本地与远端同步 |
 | 正式后端 | 已完成 Fastify、迁移兼容、outbox/worker、多应用租户、微信身份/会话，以及六角色 RBAC 和门店范围 | `backend/src/auth/**`、`database/migrations/2026061805_m02c_rbac.*.sql`、`backend/tests/**` | M01、M02-A/B/C DONE；MySQL 已验证 capability 和跨租户门店授权拒绝；下一阶段 M02-D |
 | 后台管理端 | 仅有 `admin/.gitkeep` | 当前文件扫描 | M09 未开始，不能标记 DONE |
-| 微信小程序 | 已纳管微信原生模板，并完成顾客端订单、充值和权益明细主体链路 | `miniapp/pages/index`、`miniapp/pages/store/detail`、`miniapp/pages/room/detail`、`miniapp/pages/orders/*`、`miniapp/pages/recharge/*`、`miniapp/pages/profile/*`、`miniapp/utils/api.js`、`scripts/check-miniapp-m08-a.mjs` | M08-A PARTIAL；已支持选店、门店/房间浏览、报价、预占、测试支付、订单微信预支付调起、充值微信支付调起、受控 Wi-Fi、订单列表/详情、状态历史、取消、订单权限开门、续费、换房、分享、个人中心和权益明细，仍不能标记 DONE |
+| 微信小程序 | 已纳管微信原生模板，并完成顾客端订单、充值、权益明细和下单抵扣主体链路 | `miniapp/pages/index`、`miniapp/pages/store/detail`、`miniapp/pages/room/detail`、`miniapp/pages/orders/*`、`miniapp/pages/recharge/*`、`miniapp/pages/profile/*`、`miniapp/utils/api.js`、`scripts/check-miniapp-m08-a.mjs` | M08-A PARTIAL；已支持选店、门店/房间浏览、报价、预占、测试支付、余额支付、优惠券/套餐下单抵扣、订单微信预支付调起、充值微信支付调起、受控 Wi-Fi、订单列表/详情、状态历史、取消、订单权限开门、续费、换房、分享、个人中心和权益明细，仍不能标记 DONE |
 | 数据库迁移 | 已新增 M01-B 核心 schema up/down/verify SQL、最小脱敏 seed、旧库结构 fixture、迁移计划/执行 CLI、验证结果数量门禁和 MySQL 8 集成测试 | `database/migrations/2026061601_m01b_core_schema.*.sql`、`database/seeds/2026061601_m01b_minimal_seed.sql`、`database/fixtures/2026061801_m01b_legacy_schema.sql`、`backend/src/db/migration-runner.ts`、`backend/tests/mysql-migration-roundtrip.test.mjs` | M01-B DONE；WSL MySQL 8.4.9 已验证 8 条旧库 fixture、11 条 up、3 条 verify、10 条 down，并验证租户隔离和旧金额整数分转换；不导入真实旧数据 |
 | M00 部署脚本 | 已有菜单、状态、HTTPS、Certbot、EMQX、备份检查模板 | `setup.sh`、`scripts/setup/`、`deploy/` | PARTIAL，生产未执行 |
 | 发布清单 dry-run | 可基于当前 HEAD 输出 `deployed=false` 的 release manifest，记录后端/后台/迁移尚未生成而跳过 | `scripts/setup/deploy-business.sh --dry-run .`、`scripts/dev/windows/check-release-manifest.ps1` | 可在 M00 验证结构；真实构建与生产发布待 M01/M09 后接入 |
@@ -35,6 +35,6 @@
 
 ## 下一步
 
-1. 继续 M08-A：在已完成选店、门店/房间浏览、报价、预占、测试支付、订单微信预支付调起、充值微信支付调起、受控 Wi-Fi、订单列表/详情、取消、订单权限开门、续费、换房、分享、个人中心、充值入口和权益明细基础上，补余额/优惠券/套餐下单抵扣集成。
+1. 继续 M08-A：在已完成选店、门店/房间浏览、报价、预占、测试支付、余额支付、优惠券/套餐下单抵扣、订单微信预支付调起、充值微信支付调起、受控 Wi-Fi、订单列表/详情、取消、订单权限开门、续费、换房、分享、个人中心、充值入口和权益明细基础上，补权益可视化选择器、真机合法域名、真实微信支付和实物开门验证。
 2. 继续复用 M03 门店发现、M04 订单、M05 支付、M06 设备联动和 M07 会员营销后端能力，不重复初始化小程序。
 3. M06-G 真实硬件联调仍等待生产 MQTT 账号/ACL、DeviceID 和现场实物配线。

docs/devlogs/2026-06-24-M08-A-顾客端.md

@@ -186,3 +186,28 @@ M08-A 仍为 `PARTIAL`。本次完成顾客端第一段工程闭环，但订单
 
 - 工程提交：`53f5d67`
 - 远端校验：待本轮 push 后执行 `HEAD == origin/main`。
+
+## 2026-06-25 续接：顾客端权益与余额下单抵扣
+
+- `PricingRepository.reserve` 接入优惠券/套餐权益冻结：顾客预占订单时可传入优惠券发放 ID、套餐持有 ID、套餐分钟和套餐金额抵扣，后端先按服务端价格创建预占，再在同一数据库事务中冻结权益、重算价格快照和订单应付金额。
+- `MarketingBenefitService` 与 `WalletLedgerService` 新增事务内复用方法，供订单预占、支付成功和取消释放共享同一事务边界。
+- `PaymentRepository` 新增余额支付闭环：顾客创建 `BALANCE` 支付单时跳过外部支付配置，按门店钱包先赠送后现金扣款，支付单立即成功并推进订单；测试支付与微信支付成功回调统一确认冻结权益。
+- `OrderStateRepository` 在订单取消、关闭、退款完成等释放预占/撤销权限的状态路径中释放仍处于冻结状态的优惠券和套餐。
+- 微信支付通知成功路径复用统一支付成功结算，避免测试支付和微信支付两条路径对权益确认逻辑分叉。
+- 小程序房间页新增优惠券 ID、套餐 ID、套餐分钟、套餐抵扣金额输入和“余额支付”按钮；预占时携带权益参数，支付后可直接进入订单详情。
+- `scripts/check-miniapp-m08-a.mjs` 扩展检查权益下单字段和余额支付入口。
+
+验收：
+
+- `npm run build`（`backend/`）：PASS。
+- `node scripts/check-miniapp-m08-a.mjs`：PASS。
+- `npm test`（`backend/`）：PASS。
+
+状态：
+
+- M08-A 仍为 `PARTIAL`；真机合法域名、真实微信支付、实物开门验证，以及权益选择器的可视化列表仍待继续。
+
+提交：
+
+- 工程提交：`dda2b3c`
+- 远端校验：待本轮 push 后执行 `HEAD == origin/main`。

docs/feature-status.md

@@ -17,7 +17,7 @@
 | OPS-003 | 整仓发布清单 | M00-E/M10 | PARTIAL | `59d92c0` | `deploy-business.sh --dry-run` 可在 Windows/WSL 验证当前 HEAD 的 release manifest 结构；`check-release-manifest.ps1` 已接入 `test-all.ps1`；正式构建待项目生成。 | 后端/后台尚未生成，生产菜单未执行。 | M01/M09 后接入真实构建结果，并在生产菜单 2 生成真实 release manifest。 |
 | OPS-004 | 菜单式更新与环境监测 | M00-E/M10 | PARTIAL | `292ab7f` | `setup.sh` 已接入初始化、更新、MQTT、HTTPS、状态、备份、恢复、回滚和诊断菜单；`--backup-status` 已在 WSL 验证，可检查备份工具、目录和模板。 | 未在生产 Ubuntu 执行；真实备份配置未启用。 | 生产执行后补部署记录、真实备份和恢复演练记录。 |
 | IOT-001 | MQTT Broker 生产部署 | M00/M06 | PARTIAL | `d01f771` | 菜单 3 已支持 Ubuntu 24.04 amd64 原生安装/更新与复检；正式 Topic ACL 已固定；后端实现 MQTT.js 3.1、QoS 1、持久会话、自动重连、订阅恢复、健康检查、消息上限和真实硬件烟测运行器；Windows 全量测试通过，WSL EMQX 5.8.9 服务级检查通过。 | 缺生产 EMQX 安装、正式账号、ACL/端口/备份验收；WSL 本地账号未配置，真实硬件烟测按预期 SKIP。 | 由管理员在生产菜单 3 执行并登记结果；提供生产账号、DeviceID 和实物后执行 `node dist/devices/hardware-smoke-runner.js`。 |
-| SYS-001 | 微信原生小程序 | M00-C/M08 | PARTIAL | `53f5d67` | 微信原生模板已接入顾客端登录态、选店跳转、门店详情、房间列表、报价、预占、测试支付、订单生产微信预支付调起、充值微信支付调起、受控 Wi-Fi、订单列表、订单详情、状态历史、取消入口、订单权限开门入口、续费、同门店换房、分享口令生成、个人中心余额/权益/账单汇总、充值计划/充值单入口和优惠券/套餐明细；`scripts/check-miniapp-m08-a.mjs`、相关会员/权益/充值测试通过。 | 多角色菜单、权益下单抵扣深度集成和真机联调尚未完成。 | 继续 M08-A，补余额/优惠券/套餐下单抵扣集成。 |
+| SYS-001 | 微信原生小程序 | M00-C/M08 | PARTIAL | `dda2b3c` | 微信原生模板已接入顾客端登录态、选店跳转、门店详情、房间列表、报价、预占、测试支付、订单生产微信预支付调起、充值微信支付调起、余额支付、优惠券/套餐下单抵扣参数、受控 Wi-Fi、订单列表、订单详情、状态历史、取消入口、订单权限开门入口、续费、同门店换房、分享口令生成、个人中心余额/权益/账单汇总、充值计划/充值单入口和优惠券/套餐明细；`scripts/check-miniapp-m08-a.mjs`、相关会员/权益/充值测试通过。 | 多角色菜单、权益可视化选择器和真机联调尚未完成。 | 继续 M08-A，补权益选择器、真机合法域名、真实微信支付和实物开门验证。 |
 | CFG-001 | 小程序品牌自定义 | M02-A/M03/M08 | PARTIAL | `8b8fb28` | 已建立 AppID/tenant 品牌配置表和 `/app-api/bootstrap`；同一 AppID 两租户隔离读取在 MySQL 8.4.9 实测通过。 | Logo/分享图片上传与小程序实际展示属于后续阶段。 | M03/M08 接入配置管理和小程序展示。 |
 | BKG-010 | 后台多小程序管理 | M02-A/M08/M10 | PARTIAL | `8b8fb28` | 已建立逻辑应用、租户绑定和租户配置模型；多租户 AppID 未指定租户会被拒绝。 | 尚无后台管理页面，多 AppID 真机配置未验证。 | M02-B/C 完成身份权限，M08 增加管理页面。 |
 | AUTH-001 | 多端统一小程序身份 | M02-B/M02-C/M08 | PARTIAL | `5a300a8` | 已实现微信 code 交换适配器、租户/AppID 隔离身份、JWT、服务端会话、当前用户和注销；禁用、角色/门店范围变化及管理员重置均使旧会话立即失效。 | 缺真实 AppSecret 真机联调和小程序动态角色界面。 | M08 完成小程序角色界面与真机登录。 |
@@ -32,11 +32,11 @@
 | MAP-001 | 地图选店和最近门店 | M03-C/M08 | PARTIAL | `4ac2c96` | 已实现 AppID/tenant 隔离门店发现、城市/营业筛选、按门店时区判断营业中、后端 Haversine 距离排序；小程序支持定位和手工城市降级，并可从门店卡片进入公开门店详情与房间列表。 | 地图 SDK 可视化和真机定位授权尚未验收。 | M08-A 继续补真机定位、地图展示和门店装修渲染。 |
 | QR-001 | 门店/房间场景码与 NFC | M03-D/M08 | PARTIAL | `d563078` | 已实现场景码生成、重建失效、撤销、扫码统计和二维码/NFC 统一页面解析；返回权限固定为空，旧码失效已在 MySQL 8.4.9 实测。 | 真实微信小程序码图片生成依赖可用 AppSecret 与真机环境。 | M08 接入微信小程序码接口并完成真机扫描验收。 |
 | WIFI-001 | 受控 Wi-Fi 凭据 | M03-D/M04/M08 | PARTIAL | `4ac2c96` | 正式订单与分享令牌均执行最小权限；M08-A 门店详情新增登录后受控 Wi-Fi 请求入口，不在未鉴权页面暴露密码。 | 真实到店权限、真机 Wi-Fi 连接和设备权限仍需现场联调。 | M08-A 补有效订单下的 Wi-Fi 真机连接验证。 |
-| ORD-001 | 预约下单与多方式支付 | M04/M05/M08 | PARTIAL | `e24920c` | 已完成订单全生命周期、微信支付 v3 工程闭环和团购支付；M08-A 小程序已接入报价、预占、测试支付、订单生产微信预支付调起、订单列表、订单详情、状态历史、取消测算、取消订单、续费和同门店换房入口。 | 缺真实微信和团购平台授权联调；余额/套餐支付和下单权益抵扣入口待补。 | M08-A 继续补余额/优惠券/套餐下单抵扣集成。 |
+| ORD-001 | 预约下单与多方式支付 | M04/M05/M08 | PARTIAL | `dda2b3c` | 已完成订单全生命周期、微信支付 v3 工程闭环和团购支付；M08-A 小程序已接入报价、预占、测试支付、余额支付、订单生产微信预支付调起、优惠券/套餐下单抵扣、订单列表、订单详情、状态历史、取消测算、取消订单、续费和同门店换房入口。 | 缺真实微信和团购平台授权联调；权益选择器和真机支付验收待补。 | M08-A 继续补权益可视化选择器、真机合法域名和真实微信支付验收。 |
 | WAL-001 | 充值优惠 | M07-B/M08 | PARTIAL | `53f5d67` | 已建立充值规则和充值订单表，支持有效期、适用门店、限购、启停、clientRequestId 幂等；M08-A 新增顾客端充值计划查询、充值单创建 API、小程序充值页、微信 JSAPI 预支付调起和 WeChat Pay v3 通知验签解密入账；重复支付回调不重复充值；Windows 全量回归通过。 | 真实微信商户凭据、生产合法域名和微信侧回调仍需联调。 | M08-A 继续补余额/优惠券/套餐下单抵扣集成。 |
 | WAL-002 | 门店独立会员余额 | M07-A | DONE | `63711ad` | 已建立租户/门店余额范围策略、现金/赠送双余额账户和不可变流水；充值、赠送、消费、退款、人工调整均预留 entry type；消费按赠送后现金扣款，业务号幂等，余额不足拒绝；Windows 全量后端回归通过。 | - | M07-D 聚合会员余额和权益状态。 |
 | WAL-003 | 余额账单 | M07-A/M08 | PARTIAL | `7446852` | 账单底表已包含业务类型、业务号、现金/赠送变动、变动后余额、操作人、trace 和 metadata；M07-B 充值成功后写入真实充值流水；M08-A 个人中心已展示最近钱包账单。 | 完整分页账单页面待继续；优惠券/套餐不直接写钱包流水。 | M08-A 增加分页账单或权益明细入口。 |
-| WAL-004 | 优惠券和套餐权益 | M07-C/M08 | PARTIAL | `e24920c` | 已建立优惠券模板、持券、套餐计划、持有和权益核销流水；支持满减券、时长券、适用门店/房型/房间/星期/节假日、套餐剩余时长/金额，以及订单冻结、确认核销、退回和重复请求幂等；M08-A 个人中心已展示可用/冻结券和套餐汇总，并新增本人优惠券/套餐明细页。 | 发放/购买/核销入口和订单 API 深度集成待 M08/M04 后续接入。 | M08-A 继续接入下单使用权益入口。 |
+| WAL-004 | 优惠券和套餐权益 | M07-C/M08 | PARTIAL | `dda2b3c` | 已建立优惠券模板、持券、套餐计划、持有和权益核销流水；支持满减券、时长券、适用门店/房型/房间/星期/节假日、套餐剩余时长/金额，以及订单冻结、确认核销、退回和重复请求幂等；M08-A 个人中心已展示可用/冻结券和套餐汇总，并新增本人优惠券/套餐明细页；下单预占可冻结优惠券/套餐并重算订单金额，支付成功确认核销，取消订单释放冻结权益。 | 发放/购买入口、权益可视化选择器和真机支付验收待补。 | M08-A 继续补权益选择器；M09 接入后台发放/购买和管理入口。 |
 | MEM-001 | 会员管理 | M07-D/M08 | PARTIAL | `7446852` | 已实现后台会员聚合查询服务和 `/admin-api/members`、`/admin-api/members/:id`；新增顾客端 `/app-api/profile` 和小程序个人中心，可查看注册/最近登录、订单数、消费额、余额、充值、优惠券、套餐和最近钱包流水，手机号脱敏，租户/门店范围及本人读取通过测试。 | 管理员赠券、余额人工调整、禁用、备注和后台前端页面需在 M09/M08 管理端接入并复用既有审计能力。 | M08-A 继续补顾客端权益明细；M09 接入后台会员管理页面。 |
 | GRP-001 | 团购券兑换 | M05-C | PARTIAL | `cda640b` | 已实现美团/点评、抖音、快手统一适配器，支持顾客粘贴/扫码值、管理员人工核销、Mock/API 核销、clientRequestId 幂等和券码 SHA-256 存储；重复券不能再次记账，WSL MySQL 8.4.9 实测通过。 | 缺各平台商家 API 授权，未执行真实厂商核销。 | 取得授权后配置 API endpoint/token 并执行真实验券。 |
 | GRP-002 | 美团直订 | M05-C | PARTIAL | `cda640b` | 已实现 HMAC 回调、事件幂等、外部门店/房间映射、未映射人工队列、顾客认领和团购支付订单生成；映射成功订单可进入 PAID。 | 缺美团开放平台授权和真实回调协议确认。 | 取得授权后按厂商协议实现专用签名适配并联调。 |

docs/module-status.md

@@ -7,11 +7,11 @@ execution_cursor:
   stage_status: PARTIAL
   last_completed_stage: M07-D
   next_stage: M08-A
-  last_engineering_commit: `53f5d67`
+  last_engineering_commit: `dda2b3c`
   last_push_verified: true
   base_branch: main
   blocked_reason: "M06-G 真实硬件联调缺生产 MQTT 账号/ACL、DeviceID、控制箱、门锁、插座和现场配线；已完成烟测运行器并按 BLOCKED_EXTERNAL 旁路。"
-  updated_at: 2026-06-25T13:10:00+08:00
+  updated_at: 2026-06-25T23:53:00+08:00
 ```
 
 | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 |
@@ -24,7 +24,7 @@ execution_cursor:
 | M05 会员、余额、套餐、优惠券 | PARTIAL | `1680d73` | docs/devlogs/2026-06-22-M05-D-分账与收款配置.md | M05-A/B/C/D 工程闭环已完成：统一支付、微信支付退款、团购直订、门店收款账户、分账接收方、比例策略、授权门禁、幂等分账和对账查询均通过 Windows 与 WSL MySQL 回归；真实微信/团购/分账权限未提供，模块保持 PARTIAL/BLOCKED_EXTERNAL。 |
 | M06 设备、MQTT 与真实硬件联动 | PARTIAL | `d01f771` | docs/devlogs/2026-06-24-M06-G-真实硬件联调.md | M06-A 至 F 已完成 MQTT、拓扑、协议幂等、控制箱、Sub-1G 门锁、智慧插座和订单自动联动任务；M06-G 已补真实硬件烟测运行器，缺生产 MQTT 账号/ACL、DeviceID 和实物配线，保持 BLOCKED_EXTERNAL。 |
 | M07 会员、余额、充值、优惠券和套餐营销 | DONE | `ed0d455` | docs/devlogs/2026-06-24-M07-D-会员管理.md | M07-A 已完成现金/赠送双余额账本；M07-B 已完成充值优惠；M07-C 已完成优惠券/套餐权益底表和冻结、确认、退回的可靠补偿核销服务；M07-D 已完成会员画像、订单、消费、余额、充值、优惠券和套餐聚合查询。 |
-| M08 微信原生小程序完整业务 | PARTIAL | `53f5d67` | docs/devlogs/2026-06-24-M08-A-顾客端.md | M08-A 已完成顾客端选店、门店/房间浏览、报价、预占、测试支付、订单生产微信预支付调起、充值微信支付调起与通知入账、受控 Wi-Fi、订单列表、订单详情、状态历史、取消测算、取消订单、订单权限开门、顾客续费、同门店换房、分享口令生成、个人中心余额/权益/账单汇总、充值计划/充值单入口和优惠券/套餐明细；权益下单抵扣深度集成、真机合法域名、真实微信支付和实物开门验证继续留在 M08-A。 |
+| M08 微信原生小程序完整业务 | PARTIAL | `dda2b3c` | docs/devlogs/2026-06-24-M08-A-顾客端.md | M08-A 已完成顾客端选店、门店/房间浏览、报价、预占、测试支付、订单生产微信预支付调起、充值微信支付调起与通知入账、受控 Wi-Fi、订单列表、订单详情、状态历史、取消测算、取消订单、订单权限开门、顾客续费、同门店换房、分享口令生成、个人中心余额/权益/账单汇总、充值计划/充值单入口、优惠券/套餐明细，以及优惠券/套餐/余额下单抵扣工程闭环；真机合法域名、真实微信支付、实物开门验证和权益可视化选择器继续留在 M08-A。 |
 | M09 后台管理端完整业务 | TODO | - | - | - |
 | M10 部署、域名、验收和运维闭环 | TODO | - | - | - |
 

miniapp/pages/room/detail.js

@@ -28,6 +28,10 @@ Page({
     quote: null,
     order: null,
     payment: null,
+    couponGrantId: '',
+    packageHoldingId: '',
+    packageMinutes: '',
+    packageCreditYuan: '',
   },
   onLoad(options) {
     this.setData({
@@ -36,6 +40,18 @@ Page({
     })
   },
 
+  updateBenefitField(event) {
+    const field = event.currentTarget.dataset.field
+    if (!field) return
+    this.setData({
+      [field]: event.detail.value,
+      order: null,
+      payment: null,
+      successMessage: '',
+      errorMessage: '',
+    })
+  },
+
   setDuration(event) {
     this.setData({
       durationMinutes: Number(event.currentTarget.dataset.minutes),
@@ -68,7 +84,9 @@ Page({
       const response = await request('/orders/reserve', { method: 'POST', data: payload })
       this.setData({
         order: response.data,
-        successMessage: '时段已预占，请继续支付',
+        successMessage: response.data.benefitReservation
+          ? '时段已预占，权益已冻结，请继续支付'
+          : '时段已预占，请继续支付',
       })
     })
   },
@@ -126,6 +144,30 @@ Page({
     })
   },
 
+  async createBalancePayment() {
+    if (!this.data.order || !this.data.order.orderId) {
+      this.setData({ errorMessage: '请先预占订单' })
+      return
+    }
+    await this.withRequest(async () => {
+      const response = await request('/payments', {
+        method: 'POST',
+        data: {
+          orderId: this.data.order.orderId,
+          provider: 'BALANCE',
+          clientRequestId: clientRequestId('miniapp-balance'),
+        },
+      })
+      this.setData({
+        payment: {
+          ...response.data,
+          amountText: cents(response.data.amountCents),
+        },
+        successMessage: '余额支付已完成',
+      })
+    })
+  },
+
   async completeTestPayment() {
     if (!this.data.payment || !this.data.payment.paymentId) {
       this.setData({ errorMessage: '请先创建测试支付单' })
@@ -156,6 +198,22 @@ Page({
       startAt: start.toISOString(),
       endAt: isoMinutesAfter(start, this.data.durationMinutes),
       pricingMode: this.data.pricingMode,
+      benefits: this.benefitsPayload(),
+    }
+  },
+
+  benefitsPayload() {
+    const couponGrantId = String(this.data.couponGrantId || '').trim()
+    const packageHoldingId = String(this.data.packageHoldingId || '').trim()
+    if (!couponGrantId && !packageHoldingId) return undefined
+    const packageMinutes = Number(this.data.packageMinutes || 0)
+    const packageCreditCents = Math.round(Number(this.data.packageCreditYuan || 0) * 100)
+    return {
+      couponGrantId: couponGrantId || null,
+      packageHoldingId: packageHoldingId || null,
+      packageMinutes: packageMinutes > 0 ? packageMinutes : 0,
+      packageCreditCents: packageCreditCents > 0 ? packageCreditCents : 0,
+      clientRequestId: clientRequestId('miniapp-benefit'),
     }
   },
 

miniapp/pages/room/detail.wxml

@@ -9,10 +9,19 @@
     <button size="mini" class="{{durationMinutes === 180 ? 'selected' : ''}}" data-minutes="180" bindtap="setDuration">3小时</button>
   </view>
 
+  <view class="section-title">权益抵扣</view>
+  <view class="benefit-grid">
+    <input placeholder="优惠券ID" value="{{couponGrantId}}" data-field="couponGrantId" bindinput="updateBenefitField" />
+    <input placeholder="套餐ID" value="{{packageHoldingId}}" data-field="packageHoldingId" bindinput="updateBenefitField" />
+    <input placeholder="套餐分钟" type="number" value="{{packageMinutes}}" data-field="packageMinutes" bindinput="updateBenefitField" />
+    <input placeholder="套餐抵扣元" type="digit" value="{{packageCreditYuan}}" data-field="packageCreditYuan" bindinput="updateBenefitField" />
+  </view>
+
   <view class="action-grid">
     <button loading="{{loading}}" bindtap="quote">报价</button>
     <button loading="{{loading}}" bindtap="reserve">预占</button>
     <button loading="{{loading}}" bindtap="createWechatPayment">微信支付</button>
+    <button loading="{{loading}}" bindtap="createBalancePayment">余额支付</button>
     <button loading="{{loading}}" bindtap="createTestPayment">测试支付</button>
     <button loading="{{loading}}" bindtap="completeTestPayment">完成测试支付</button>
   </view>
@@ -30,6 +39,8 @@
     <view class="result-title">订单</view>
     <view>订单编号：{{order.orderId}}</view>
     <view wx:if="{{order.reservationId}}">预占编号：{{order.reservationId}}</view>
+    <view wx:if="{{order.quote.discountCents}}">优惠抵扣：{{order.quote.discountCents}}分</view>
+    <view wx:if="{{order.quote.packageCreditCents}}">套餐抵扣：{{order.quote.packageCreditCents}}分</view>
     <button size="mini" data-order-id="{{order.orderId}}" bindtap="openOrder">查看订单</button>
   </view>
 

miniapp/pages/room/detail.wxss

@@ -22,13 +22,24 @@
 }
 
 .duration-row,
-.action-grid {
+.action-grid,
+.benefit-grid {
   display: flex;
   gap: 16rpx;
   flex-wrap: wrap;
   margin-bottom: 24rpx;
 }
 
+.benefit-grid input {
+  box-sizing: border-box;
+  flex: 1 1 280rpx;
+  min-height: 72rpx;
+  padding: 0 20rpx;
+  border: 1rpx solid #d9dde5;
+  border-radius: 12rpx;
+  background: #ffffff;
+}
+
 .action-grid button {
   flex: 1 1 280rpx;
 }

scripts/check-miniapp-m08-a.mjs

@@ -48,6 +48,14 @@ for (const route of [
   assert.match(room, new RegExp(route.replace('/', '\\/')));
 }
 assert.match(room, /requestWechatPayment/);
+for (const pattern of [
+  'couponGrantId',
+  'packageHoldingId',
+  'packageCreditCents',
+  "provider: 'BALANCE'"
+]) {
+  assert.match(room, new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+}
 
 const orders = read('miniapp/pages/orders/list.js')
   + read('miniapp/pages/orders/detail.js');