feat(M03-D): 完成场景码NFC与受控WiFi

backend/package.json

@@ -17,7 +17,7 @@
     "db:migrate:verify": "npm run build && node dist/db/migrate-cli.js verify",
     "db:migrate:down": "npm run build && node dist/db/migrate-cli.js down",
     "test:mysql:migration": "npm run build && node tests/mysql-migration-roundtrip.test.mjs",
-    "test": "npm run build && node tests/backend-contract.test.mjs && node tests/migration-contract.test.mjs && node tests/mysql-pool-contract.test.mjs && node tests/migration-runner.test.mjs && node tests/legacy-money.test.mjs && node tests/legacy-read-repository.test.mjs && node tests/task-repository.test.mjs && node tests/platform-config-repository.test.mjs && node tests/auth.test.mjs && node tests/rbac.test.mjs && node tests/user-management.test.mjs && node tests/store-room.test.mjs && node tests/content-management.test.mjs && node tests/store-discovery.test.mjs"
+    "test": "npm run build && node tests/backend-contract.test.mjs && node tests/migration-contract.test.mjs && node tests/mysql-pool-contract.test.mjs && node tests/migration-runner.test.mjs && node tests/legacy-money.test.mjs && node tests/legacy-read-repository.test.mjs && node tests/task-repository.test.mjs && node tests/platform-config-repository.test.mjs && node tests/auth.test.mjs && node tests/rbac.test.mjs && node tests/user-management.test.mjs && node tests/store-room.test.mjs && node tests/content-management.test.mjs && node tests/store-discovery.test.mjs && node tests/store-access.test.mjs"
   },
   "dependencies": {
     "@fastify/cors": "^11.2.0",

backend/src/app.ts

@@ -25,6 +25,10 @@ import {
   registerStoreDiscoveryRoutes,
   type StoreDiscoveryRouteOptions
 } from './routes/store-discovery.js';
+import {
+  registerStoreAccessRoutes,
+  type StoreAccessRouteOptions
+} from './routes/store-access.js';
 
 export interface BuildAppOptions {
   config?: AppConfig;
@@ -34,6 +38,7 @@ export interface BuildAppOptions {
   storeRoom?: StoreRoomRouteOptions;
   content?: ContentRouteOptions;
   storeDiscovery?: StoreDiscoveryRouteOptions;
+  storeAccess?: StoreAccessRouteOptions;
 }
 
 declare module 'fastify' {
@@ -94,6 +99,9 @@ export async function buildApp(options: BuildAppOptions = {}): Promise<FastifyIn
   if (options.storeDiscovery) {
     await registerStoreDiscoveryRoutes(app, options.storeDiscovery);
   }
+  if (options.storeAccess) {
+    await registerStoreAccessRoutes(app, options.storeAccess);
+  }
 
   return app;
 }

backend/src/db/migration-runner.ts

@@ -29,7 +29,8 @@ const migrationFiles: Record<MigrationDirection, readonly string[]> = {
     'database/migrations/2026061806_m02d_user_management.up.sql',
     'database/migrations/2026061807_m03a_store_room_domain.up.sql',
     'database/migrations/2026061808_m03b_decoration_ads_media.up.sql',
-    'database/migrations/2026061809_m03c_store_discovery.up.sql'
+    'database/migrations/2026061809_m03c_store_discovery.up.sql',
+    'database/migrations/2026061810_m03d_scene_wifi_access.up.sql'
   ],
   verify: [
     'database/migrations/2026061601_m01b_core_schema.verify.sql',
@@ -40,9 +41,11 @@ const migrationFiles: Record<MigrationDirection, readonly string[]> = {
     'database/migrations/2026061806_m02d_user_management.verify.sql',
     'database/migrations/2026061807_m03a_store_room_domain.verify.sql',
     'database/migrations/2026061808_m03b_decoration_ads_media.verify.sql',
-    'database/migrations/2026061809_m03c_store_discovery.verify.sql'
+    'database/migrations/2026061809_m03c_store_discovery.verify.sql',
+    'database/migrations/2026061810_m03d_scene_wifi_access.verify.sql'
   ],
   down: [
+    'database/migrations/2026061810_m03d_scene_wifi_access.down.sql',
     'database/migrations/2026061809_m03c_store_discovery.down.sql',
     'database/migrations/2026061808_m03b_decoration_ads_media.down.sql',
     'database/migrations/2026061807_m03a_store_room_domain.down.sql',
@@ -176,7 +179,8 @@ export async function executeMigrationPlan(
         1, 3, 1,
         3, 6, 13, 1,
         3, 3, 1,
-        2, 2, 1
+        2, 2, 1,
+        3, 3, 1
       ][index] ?? 1;
       if (!Array.isArray(result) || result.length < minimumRows) {
         throw new Error(

backend/src/routes/store-access.ts

@@ -0,0 +1,170 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import { z } from 'zod';
+import type { AuthRepository } from '../auth/auth-repository.js';
+import { authenticateAccessToken } from '../auth/authenticate.js';
+import type { AccessProfile } from '../auth/rbac-repository.js';
+import type { ManagementActor } from '../auth/user-management-repository.js';
+import {
+  StoreAccessError,
+  type StoreAccessRepository
+} from '../stores/access-repository.js';
+
+const idSchema = z.object({ id: z.string().regex(/^[1-9]\d{0,19}$/) });
+const storeIdSchema = z.object({ storeId: z.string().regex(/^[1-9]\d{0,19}$/) });
+const sceneSchema = z.object({
+  targetType: z.enum(['STORE', 'ROOM']),
+  storeId: z.string().regex(/^[1-9]\d{0,19}$/),
+  roomId: z.string().regex(/^[1-9]\d{0,19}$/).optional()
+}).refine((value) => value.targetType === 'STORE' || value.roomId !== undefined);
+const resolveSchema = z.object({
+  code: z.string().trim().min(12).max(32),
+  sourceType: z.enum(['QRCODE', 'NFC']).default('QRCODE')
+});
+
+export interface StoreAccessRouteOptions {
+  repository: Pick<StoreAccessRepository,
+    'regenerateScene' | 'revokeScene' | 'resolveScene' | 'sceneStats' | 'getWifi'>;
+  authRepository: Pick<AuthRepository, 'validateSession'>;
+  accessControl: { getAccessProfile(tenantId: string, userId: string): Promise<AccessProfile> };
+  jwtSecret: string;
+}
+
+export async function registerStoreAccessRoutes(
+  app: FastifyInstance, options: StoreAccessRouteOptions
+) {
+  app.post('/admin-api/scene-codes/regenerate', async (request, reply) => {
+    const actor = await requireManager(request, reply, options);
+    const body = sceneSchema.safeParse(request.body);
+    if (!actor || !body.success) return actor ? invalid(reply, request.traceId) : undefined;
+    return handle(reply, request.traceId, async () => reply.status(201).send({
+      code: 0,
+      data: await options.repository.regenerateScene(actor, body.data),
+      traceId: request.traceId
+    }));
+  });
+  app.post('/admin-api/scene-codes/:id/revoke', async (request, reply) => {
+    const actor = await requireManager(request, reply, options);
+    const params = idSchema.safeParse(request.params);
+    const query = storeIdSchema.safeParse(request.query);
+    if (!actor || !params.success || !query.success) {
+      return actor ? invalid(reply, request.traceId) : undefined;
+    }
+    return handle(reply, request.traceId, async () => ({
+      code: 0,
+      data: await options.repository.revokeScene(actor, params.data.id, query.data.storeId),
+      traceId: request.traceId
+    }));
+  });
+  app.get('/admin-api/stores/:storeId/scene-code-stats', async (request, reply) => {
+    const actor = await requireManager(request, reply, options);
+    const params = storeIdSchema.safeParse(request.params);
+    if (!actor || !params.success) return actor ? invalid(reply, request.traceId) : undefined;
+    return handle(reply, request.traceId, async () => ({
+      code: 0,
+      data: await options.repository.sceneStats(actor, params.data.storeId),
+      traceId: request.traceId
+    }));
+  });
+  app.post('/app-api/scenes/resolve', async (request, reply) => {
+    const body = resolveSchema.safeParse(request.body);
+    if (!body.success) return invalid(reply, request.traceId);
+    return handle(reply, request.traceId, async () => ({
+      code: 0,
+      data: await options.repository.resolveScene({
+        ...body.data,
+        traceId: request.traceId,
+        ip: request.ip,
+        userAgent: request.headers['user-agent'] ?? ''
+      }),
+      traceId: request.traceId
+    }));
+  });
+  app.get('/app-api/stores/:storeId/wifi', async (request, reply) => {
+    const auth = await authenticateAccessToken(
+      request.headers.authorization, options.authRepository, options.jwtSecret
+    );
+    const params = storeIdSchema.safeParse(request.params);
+    if (!auth) {
+      return reply.status(401).send({
+        code: 'AUTH_SESSION_INVALID', message: 'Authentication required.',
+        traceId: request.traceId
+      });
+    }
+    if (!params.success) return invalid(reply, request.traceId);
+    const access = await options.accessControl.getAccessProfile(
+      auth.session.tenantId, auth.session.user.id
+    );
+    return handle(reply, request.traceId, async () => ({
+      code: 0,
+      data: await options.repository.getWifi({
+        tenantId: auth.session.tenantId,
+        userId: auth.session.user.id,
+        access,
+        storeId: params.data.storeId,
+        traceId: request.traceId,
+        ip: request.ip,
+        userAgent: request.headers['user-agent'] ?? ''
+      }),
+      traceId: request.traceId
+    }));
+  });
+}
+
+async function requireManager(
+  request: FastifyRequest, reply: FastifyReply, options: StoreAccessRouteOptions
+): Promise<ManagementActor | null> {
+  const auth = await authenticateAccessToken(
+    request.headers.authorization, options.authRepository, options.jwtSecret
+  );
+  if (!auth) {
+    reply.status(401).send({
+      code: 'AUTH_SESSION_INVALID', message: 'Authentication required.',
+      traceId: request.traceId
+    });
+    return null;
+  }
+  const access = await options.accessControl.getAccessProfile(
+    auth.session.tenantId, auth.session.user.id
+  );
+  if (!access.capabilities.some((item) =>
+    item === 'store.operation.write' || item === 'tenant.manage'
+  ) && !access.roles.includes('PLATFORM_ADMIN')) {
+    reply.status(403).send({
+      code: 'SCENE_MANAGEMENT_FORBIDDEN',
+      message: 'Store management permission is required.',
+      traceId: request.traceId
+    });
+    return null;
+  }
+  return {
+    tenantId: auth.session.tenantId,
+    userId: auth.session.user.id,
+    access,
+    traceId: request.traceId,
+    ip: request.ip,
+    userAgent: request.headers['user-agent'] ?? ''
+  };
+}
+
+async function handle(reply: FastifyReply, traceId: string, work: () => Promise<unknown>) {
+  try {
+    return await work();
+  } catch (error) {
+    if (!(error instanceof StoreAccessError)) throw error;
+    const forbidden = error.code.endsWith('_FORBIDDEN');
+    const notFound = error.code.endsWith('_NOT_FOUND') || error.code === 'SCENE_CODE_INVALID';
+    return reply.status(forbidden ? 403 : notFound ? 404 : 400).send({
+      code: error.code,
+      message: 'The scene or Wi-Fi request is invalid or not allowed.',
+      traceId
+    });
+  }
+}
+
+function invalid(reply: FastifyReply, traceId: string) {
+  return reply.status(400).send({
+    code: 'INVALID_STORE_ACCESS_REQUEST',
+    message: 'The scene or Wi-Fi request is invalid.',
+    traceId
+  });
+}

backend/src/server.ts

@@ -11,6 +11,7 @@ import { ContentRepository } from './content/content-repository.js';
 import { MediaStorage } from './content/media-storage.js';
 import { resolve } from 'node:path';
 import { StoreDiscoveryRepository } from './stores/store-discovery-repository.js';
+import { StoreAccessRepository } from './stores/access-repository.js';
 
 const config = loadConfig();
 const pool = createMySqlPool(config);
@@ -49,6 +50,12 @@ const app = await buildApp({
   storeDiscovery: {
     repository: new StoreDiscoveryRepository(pool),
     tenancy: authRepository
+  },
+  storeAccess: {
+    repository: new StoreAccessRepository(pool),
+    authRepository,
+    accessControl,
+    jwtSecret: config.auth.jwtSecret
   }
 });
 app.addHook('onClose', async () => {

backend/src/stores/access-repository.ts

@@ -0,0 +1,219 @@
+import { randomBytes } from 'node:crypto';
+import type { PoolConnection, ResultSetHeader, RowDataPacket } from 'mysql2/promise';
+import type { AccessProfile } from '../auth/rbac-repository.js';
+import type { ManagementActor } from '../auth/user-management-repository.js';
+import type { MySqlPool } from '../db/mysql.js';
+
+interface SceneRow extends RowDataPacket {
+  id: string;
+  tenantId: string;
+  targetType: 'STORE' | 'ROOM';
+  storeId: string;
+  roomId: string | null;
+  generation: number;
+  scanCount: number;
+}
+interface WifiRow extends RowDataPacket { ssid: string; password: string }
+interface CountRow extends RowDataPacket { total: number }
+
+export class StoreAccessError extends Error {
+  constructor(public readonly code: string) { super(code); }
+}
+
+export class StoreAccessRepository {
+  constructor(private readonly pool: MySqlPool) {}
+
+  async regenerateScene(actor: ManagementActor, input: {
+    targetType: 'STORE' | 'ROOM'; storeId: string; roomId?: string;
+  }) {
+    this.assertStoreManager(actor.access, input.storeId);
+    return this.transaction(async (connection) => {
+      await this.assertTarget(connection, actor.tenantId, input);
+      const [generations] = await connection.execute<CountRow[]>(
+        `SELECT COALESCE(MAX(generation), 0) + 1 AS total
+         FROM qipai_scene_codes
+         WHERE tenant_id = ? AND target_type = ? AND store_id = ?
+           AND room_id <=> ? FOR UPDATE`,
+        [actor.tenantId, input.targetType, input.storeId, input.roomId ?? null]
+      );
+      await connection.execute(
+        `UPDATE qipai_scene_codes SET status = 'REVOKED', revoked_at = UTC_TIMESTAMP(3)
+         WHERE tenant_id = ? AND target_type = ? AND store_id = ?
+           AND room_id <=> ? AND status = 'ACTIVE'`,
+        [actor.tenantId, input.targetType, input.storeId, input.roomId ?? null]
+      );
+      const code = randomBytes(12).toString('base64url');
+      const generation = Number(generations[0]?.total ?? 1);
+      const [result] = await connection.execute<ResultSetHeader>(
+        `INSERT INTO qipai_scene_codes
+          (tenant_id, code, target_type, store_id, room_id, generation, created_by)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+        [actor.tenantId, code, input.targetType, input.storeId,
+          input.roomId ?? null, generation, actor.userId]
+      );
+      await this.audit(connection, actor, 'SCENE_CODE_REGENERATED', 'SCENE_CODE', String(result.insertId));
+      return { sceneCodeId: String(result.insertId), code, generation };
+    });
+  }
+
+  async revokeScene(actor: ManagementActor, sceneCodeId: string, storeId: string) {
+    this.assertStoreManager(actor.access, storeId);
+    const [result] = await this.pool.execute<ResultSetHeader>(
+      `UPDATE qipai_scene_codes SET status = 'REVOKED', revoked_at = UTC_TIMESTAMP(3)
+       WHERE tenant_id = ? AND id = ? AND store_id = ? AND status = 'ACTIVE'`,
+      [actor.tenantId, sceneCodeId, storeId]
+    );
+    if (result.affectedRows !== 1) throw new StoreAccessError('SCENE_CODE_NOT_FOUND');
+    return { sceneCodeId, revoked: true };
+  }
+
+  async resolveScene(input: {
+    code: string; sourceType: 'QRCODE' | 'NFC'; traceId: string;
+    ip: string; userAgent: string; userId?: string;
+  }) {
+    return this.transaction(async (connection) => {
+      const [rows] = await connection.execute<SceneRow[]>(
+        `SELECT id, tenant_id AS tenantId, target_type AS targetType,
+                store_id AS storeId, room_id AS roomId, generation,
+                scan_count AS scanCount
+         FROM qipai_scene_codes
+         WHERE code = ? AND status = 'ACTIVE' LIMIT 1 FOR UPDATE`,
+        [input.code]
+      );
+      const scene = rows[0];
+      if (!scene) throw new StoreAccessError('SCENE_CODE_INVALID');
+      await connection.execute(
+        `UPDATE qipai_scene_codes SET scan_count = scan_count + 1,
+          last_scanned_at = UTC_TIMESTAMP(3) WHERE id = ?`,
+        [scene.id]
+      );
+      await connection.execute(
+        `INSERT INTO qipai_scene_scan_events
+          (tenant_id, scene_code_id, source_type, user_id, trace_id, ip, user_agent)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+        [scene.tenantId, scene.id, input.sourceType, input.userId ?? null,
+          input.traceId, input.ip, input.userAgent.slice(0, 255)]
+      );
+      return {
+        targetType: scene.targetType,
+        storeId: String(scene.storeId),
+        roomId: scene.roomId === null ? null : String(scene.roomId),
+        page: scene.targetType === 'ROOM' ? '/pages/room/detail' : '/pages/store/detail',
+        permissions: []
+      };
+    });
+  }
+
+  async sceneStats(actor: ManagementActor, storeId: string) {
+    this.assertStoreManager(actor.access, storeId);
+    const [rows] = await this.pool.execute<SceneRow[]>(
+      `SELECT id, tenant_id AS tenantId, target_type AS targetType,
+              store_id AS storeId, room_id AS roomId, generation,
+              scan_count AS scanCount
+       FROM qipai_scene_codes
+       WHERE tenant_id = ? AND store_id = ? AND status = 'ACTIVE'
+       ORDER BY target_type, room_id`,
+      [actor.tenantId, storeId]
+    );
+    return rows.map((row) => ({
+      sceneCodeId: String(row.id),
+      targetType: row.targetType,
+      storeId: String(row.storeId),
+      roomId: row.roomId === null ? null : String(row.roomId),
+      generation: row.generation,
+      scanCount: Number(row.scanCount)
+    }));
+  }
+
+  async getWifi(input: {
+    tenantId: string; userId: string; access: AccessProfile; storeId: string;
+    traceId: string; ip: string; userAgent: string;
+  }) {
+    const manager = this.canManageStore(input.access, input.storeId);
+    if (!manager) {
+      const [rows] = await this.pool.execute<CountRow[]>(
+        `SELECT COUNT(*) AS total
+         FROM qipai_order_user_access a
+         INNER JOIN qipai_orders o
+           ON o.id = a.order_id AND o.tenant_id = a.tenant_id AND o.deleted_at IS NULL
+         WHERE a.tenant_id = ? AND a.user_id = ? AND a.revoked_at IS NULL
+           AND o.store_id = ? AND o.status IN ('PAID', 'CONFIRMED', 'IN_USE')
+           AND UTC_TIMESTAMP(3) BETWEEN DATE_SUB(o.start_at, INTERVAL 30 MINUTE) AND o.end_at`,
+        [input.tenantId, input.userId, input.storeId]
+      );
+      if (Number(rows[0]?.total ?? 0) === 0) throw new StoreAccessError('WIFI_ACCESS_FORBIDDEN');
+    }
+    const [rows] = await this.pool.execute<WifiRow[]>(
+      `SELECT wifi_ssid AS ssid, wifi_password AS password
+       FROM qipai_stores
+       WHERE tenant_id = ? AND id = ? AND deleted_at IS NULL LIMIT 1`,
+      [input.tenantId, input.storeId]
+    );
+    if (!rows[0] || !rows[0].ssid) throw new StoreAccessError('WIFI_NOT_CONFIGURED');
+    await this.pool.execute(
+      `INSERT INTO qipai_audit_logs
+        (tenant_id, actor_type, actor_id, action, resource_type, resource_id,
+         trace_id, ip, user_agent, metadata)
+       VALUES (?, 'USER', ?, 'WIFI_CREDENTIAL_ACCESSED', 'STORE', ?, ?, ?, ?,
+         JSON_OBJECT('ssid', ?, 'passwordReturned', TRUE))`,
+      [input.tenantId, input.userId, input.storeId, input.traceId,
+        input.ip, input.userAgent.slice(0, 255), rows[0].ssid]
+    );
+    return rows[0];
+  }
+
+  private assertStoreManager(access: AccessProfile, storeId: string) {
+    if (!this.canManageStore(access, storeId)) throw new StoreAccessError('STORE_SCOPE_FORBIDDEN');
+  }
+
+  private canManageStore(access: AccessProfile, storeId: string) {
+    return access.capabilities.includes('tenant.manage')
+      || access.roles.includes('PLATFORM_ADMIN')
+      || (access.capabilities.includes('store.operation.write') && access.storeIds.includes(storeId));
+  }
+
+  private async assertTarget(
+    connection: PoolConnection, tenantId: string,
+    input: { targetType: 'STORE' | 'ROOM'; storeId: string; roomId?: string }
+  ) {
+    if (input.targetType === 'ROOM' && !input.roomId) throw new StoreAccessError('ROOM_REQUIRED');
+    const sql = input.targetType === 'ROOM'
+      ? `SELECT COUNT(*) AS total FROM qipai_rooms
+         WHERE tenant_id = ? AND store_id = ? AND id = ? AND deleted_at IS NULL`
+      : `SELECT COUNT(*) AS total FROM qipai_stores
+         WHERE tenant_id = ? AND id = ? AND deleted_at IS NULL`;
+    const params: string[] = input.targetType === 'ROOM'
+      ? [tenantId, input.storeId, input.roomId as string] : [tenantId, input.storeId];
+    const [rows] = await connection.execute<CountRow[]>(sql, params);
+    if (Number(rows[0]?.total ?? 0) !== 1) throw new StoreAccessError('SCENE_TARGET_NOT_FOUND');
+  }
+
+  private async audit(
+    connection: PoolConnection, actor: ManagementActor,
+    action: string, resourceType: string, resourceId: string
+  ) {
+    await connection.execute(
+      `INSERT INTO qipai_audit_logs
+        (tenant_id, actor_type, actor_id, action, resource_type, resource_id,
+         trace_id, ip, user_agent, metadata)
+       VALUES (?, 'USER', ?, ?, ?, ?, ?, ?, ?, JSON_OBJECT())`,
+      [actor.tenantId, actor.userId, action, resourceType, resourceId,
+        actor.traceId, actor.ip, actor.userAgent.slice(0, 255)]
+    );
+  }
+
+  private async transaction<T>(work: (connection: PoolConnection) => Promise<T>) {
+    const connection = await this.pool.getConnection();
+    try {
+      await connection.beginTransaction();
+      const result = await work(connection);
+      await connection.commit();
+      return result;
+    } catch (error) {
+      await connection.rollback();
+      throw error;
+    } finally {
+      connection.release();
+    }
+  }
+}

backend/tests/migration-contract.test.mjs

@@ -36,6 +36,9 @@ const contentVerifySql = read('database/migrations/2026061808_m03b_decoration_ad
 const discoveryUpSql = read('database/migrations/2026061809_m03c_store_discovery.up.sql');
 const discoveryDownSql = read('database/migrations/2026061809_m03c_store_discovery.down.sql');
 const discoveryVerifySql = read('database/migrations/2026061809_m03c_store_discovery.verify.sql');
+const accessUpSql = read('database/migrations/2026061810_m03d_scene_wifi_access.up.sql');
+const accessDownSql = read('database/migrations/2026061810_m03d_scene_wifi_access.down.sql');
+const accessVerifySql = read('database/migrations/2026061810_m03d_scene_wifi_access.verify.sql');
 
 const coreTables = [
   'qipai_schema_migrations',
@@ -170,5 +173,15 @@ for (const column of ['city', 'district']) {
 }
 assert.match(discoveryUpSql, /idx_qipai_stores_tenant_city_status/);
 assert.match(discoveryUpSql, /idx_qipai_stores_tenant_coordinates/);
+for (const table of [
+  'qipai_scene_codes', 'qipai_scene_scan_events', 'qipai_order_user_access'
+]) {
+  assert.match(accessUpSql, new RegExp(`CREATE TABLE IF NOT EXISTS ${table}`));
+  assert.match(accessDownSql, new RegExp(`DROP TABLE IF EXISTS ${table}`));
+  assert.match(accessVerifySql, new RegExp(`'${table}'`));
+}
+assert.match(accessUpSql, /scan_count BIGINT UNSIGNED/);
+assert.match(accessUpSql, /target_type = 'STORE'/);
+assert.match(accessUpSql, /PRIMARY KEY \(tenant_id, order_id, user_id\)/);
 
-console.log('PASS: M01-B through M03-C migration contracts are present.');
+console.log('PASS: M01-B through M03-D migration contracts are present.');

backend/tests/migration-runner.test.mjs

@@ -20,7 +20,8 @@ assert.match(plan.file, /2026061805_m02c_rbac\.up\.sql/);
 assert.match(plan.file, /2026061806_m02d_user_management\.up\.sql/);
 assert.match(plan.file, /2026061807_m03a_store_room_domain\.up\.sql/);
 assert.match(plan.file, /2026061808_m03b_decoration_ads_media\.up\.sql/);
-assert.match(plan.file, /2026061809_m03c_store_discovery\.up\.sql$/);
+assert.match(plan.file, /2026061809_m03c_store_discovery\.up\.sql/);
+assert.match(plan.file, /2026061810_m03d_scene_wifi_access\.up\.sql$/);
 assert.match(plan.checksum, /^[a-f0-9]{64}$/);
 assert.ok(plan.statements.length >= 11);
 

backend/tests/mysql-migration-roundtrip.test.mjs

@@ -16,6 +16,7 @@ import { UserManagementRepository } from '../dist/auth/user-management-repositor
 import { StoreRoomRepository, StoreRoomError } from '../dist/stores/store-room-repository.js';
 import { ContentRepository, ContentError } from '../dist/content/content-repository.js';
 import { StoreDiscoveryRepository } from '../dist/stores/store-discovery-repository.js';
+import { StoreAccessRepository, StoreAccessError } from '../dist/stores/access-repository.js';
 import {
   executeMigrationPlan,
   loadMigrationPlan,
@@ -31,6 +32,7 @@ const expectedTables = [
   'qipai_legacy_table_mappings',
   'qipai_media_assets',
   'qipai_members',
+  'qipai_order_user_access',
   'qipai_orders',
   'qipai_outbox_events',
   'qipai_payments',
@@ -41,6 +43,8 @@ const expectedTables = [
   'qipai_room_categories',
   'qipai_room_disabled_periods',
   'qipai_rooms',
+  'qipai_scene_codes',
+  'qipai_scene_scan_events',
   'qipai_schema_migrations',
   'qipai_store_business_hours',
   'qipai_store_decorations',
@@ -73,10 +77,11 @@ async function readMigrationVersions(pool) {
   const [rows] = await pool.query(
     `SELECT version, name
      FROM qipai_schema_migrations
-     WHERE version IN (?, ?, ?, ?, ?, ?, ?, ?, ?)
+     WHERE version IN (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
      ORDER BY version`,
     ['2026061601', '2026061802', '2026061803', '2026061804',
-      '2026061805', '2026061806', '2026061807', '2026061808', '2026061809']
+      '2026061805', '2026061806', '2026061807', '2026061808', '2026061809',
+      '2026061810']
   );
   return rows;
 }
@@ -425,6 +430,103 @@ async function assertStoreDiscovery(pool, context) {
   })).length, 0);
 }
 
+async function assertSceneAndWifiAccess(pool, context) {
+  const [adminRows] = await pool.query(
+    `SELECT u.id FROM qipai_users u
+     INNER JOIN qipai_user_roles ur ON ur.tenant_id = u.tenant_id AND ur.user_id = u.id
+     INNER JOIN qipai_roles r ON r.id = ur.role_id AND r.tenant_id = ur.tenant_id
+     WHERE u.tenant_id = ? AND r.code = 'TENANT_ADMIN' LIMIT 1`,
+    [context.tenantId]
+  );
+  const [customerRows] = await pool.query(
+    `SELECT u.id FROM qipai_users u
+     INNER JOIN qipai_user_identities i
+       ON i.tenant_id = u.tenant_id AND i.user_id = u.id
+     WHERE u.tenant_id = ? AND i.openid = 'm02b-openid-a' LIMIT 1`,
+    [context.tenantId]
+  );
+  const [targetRows] = await pool.query(
+    `SELECT s.id AS storeId, r.id AS roomId
+     FROM qipai_stores s
+     INNER JOIN qipai_rooms r ON r.tenant_id = s.tenant_id AND r.store_id = s.id
+     WHERE s.tenant_id = ? AND s.name = 'M03A Store' LIMIT 1`,
+    [context.tenantId]
+  );
+  const adminId = String(adminRows[0].id);
+  const customerId = String(customerRows[0].id);
+  const storeId = String(targetRows[0].storeId);
+  const roomId = String(targetRows[0].roomId);
+  const rbac = new RbacRepository(pool);
+  const adminAccess = await rbac.getAccessProfile(context.tenantId, adminId);
+  const customerAccess = await rbac.getAccessProfile(context.tenantId, customerId);
+  const actor = {
+    tenantId: context.tenantId, userId: adminId, access: adminAccess,
+    traceId: 'm03d-live-test', ip: '127.0.0.1', userAgent: 'M03-D live test'
+  };
+  const repository = new StoreAccessRepository(pool);
+  const first = await repository.regenerateScene(actor, {
+    targetType: 'ROOM', storeId, roomId
+  });
+  const firstResolved = await repository.resolveScene({
+    code: first.code, sourceType: 'QRCODE', traceId: 'm03d-scan-1',
+    ip: '127.0.0.1', userAgent: 'M03-D scan'
+  });
+  assert.equal(firstResolved.roomId, roomId);
+  assert.deepEqual(firstResolved.permissions, []);
+  const second = await repository.regenerateScene(actor, {
+    targetType: 'ROOM', storeId, roomId
+  });
+  assert.equal(second.generation, 2);
+  await assert.rejects(
+    () => repository.resolveScene({
+      code: first.code, sourceType: 'NFC', traceId: 'm03d-old-code',
+      ip: '127.0.0.1', userAgent: 'M03-D old code'
+    }),
+    (error) => error instanceof StoreAccessError && error.code === 'SCENE_CODE_INVALID'
+  );
+  await repository.resolveScene({
+    code: second.code, sourceType: 'NFC', traceId: 'm03d-scan-2',
+    ip: '127.0.0.1', userAgent: 'M03-D NFC'
+  });
+  assert.equal((await repository.sceneStats(actor, storeId))[0].scanCount, 1);
+
+  await assert.rejects(
+    () => repository.getWifi({
+      tenantId: context.tenantId, userId: customerId, access: customerAccess, storeId,
+      traceId: 'm03d-wifi-denied', ip: '127.0.0.1', userAgent: 'M03-D denied'
+    }),
+    (error) => error instanceof StoreAccessError && error.code === 'WIFI_ACCESS_FORBIDDEN'
+  );
+  const [orderResult] = await pool.query(
+    `INSERT INTO qipai_orders
+      (tenant_id, store_id, room_id, order_no, status, start_at, end_at)
+     VALUES (?, ?, ?, 'M03D-WIFI-ORDER', 'IN_USE',
+       DATE_SUB(UTC_TIMESTAMP(3), INTERVAL 10 MINUTE),
+       DATE_ADD(UTC_TIMESTAMP(3), INTERVAL 50 MINUTE))`,
+    [context.tenantId, storeId, roomId]
+  );
+  await pool.query(
+    `INSERT INTO qipai_order_user_access (tenant_id, order_id, user_id)
+     VALUES (?, ?, ?)`,
+    [context.tenantId, orderResult.insertId, customerId]
+  );
+  const wifi = await repository.getWifi({
+    tenantId: context.tenantId, userId: customerId, access: customerAccess, storeId,
+    traceId: 'm03d-wifi-allowed', ip: '127.0.0.1', userAgent: 'M03-D allowed'
+  });
+  assert.equal(wifi.ssid, 'M03A-WIFI');
+  assert.equal(wifi.password, 'sanitized-password');
+  const [auditRows] = await pool.query(
+    `SELECT CAST(metadata AS CHAR) AS metadata
+     FROM qipai_audit_logs
+     WHERE tenant_id = ? AND trace_id = 'm03d-wifi-allowed'`,
+    [context.tenantId]
+  );
+  assert.equal(auditRows.length, 1);
+  assert.match(auditRows[0].metadata, /M03A-WIFI/);
+  assert.doesNotMatch(auditRows[0].metadata, /sanitized-password/);
+}
+
 async function assertContentManagement(pool, context) {
   const [adminRows] = await pool.query(
     `SELECT u.id FROM qipai_users u
@@ -521,7 +623,8 @@ try {
     { version: '2026061806', name: 'm02d_user_management' },
     { version: '2026061807', name: 'm03a_store_room_domain' },
     { version: '2026061808', name: 'm03b_decoration_ads_media' },
-    { version: '2026061809', name: 'm03c_store_discovery' }
+    { version: '2026061809', name: 'm03c_store_discovery' },
+    { version: '2026061810', name: 'm03d_scene_wifi_access' }
   ]);
   await assertTaskDurability(pool);
   const loginContext = await assertPlatformTenantIsolation(pool);
@@ -530,6 +633,7 @@ try {
   await assertStoreRoomDomain(pool, loginContext);
   await assertContentManagement(pool, loginContext);
   await assertStoreDiscovery(pool, loginContext);
+  await assertSceneAndWifiAccess(pool, loginContext);
   await assertLegacyCompatibility(pool);
   console.log('PASS: first up, verify, tenant isolation and revocable auth checks completed.');
 
@@ -550,7 +654,8 @@ try {
     { version: '2026061806', name: 'm02d_user_management' },
     { version: '2026061807', name: 'm03a_store_room_domain' },
     { version: '2026061808', name: 'm03b_decoration_ads_media' },
-    { version: '2026061809', name: 'm03c_store_discovery' }
+    { version: '2026061809', name: 'm03c_store_discovery' },
+    { version: '2026061810', name: 'm03d_scene_wifi_access' }
   ]);
   await assertLegacyCompatibility(pool);
   console.log('PASS: second up and verify restored the schema.');
@@ -598,7 +703,13 @@ try {
       'platform advertisement rejection',
       'city fallback store filtering',
       'server-side distance sorting',
-      'empty manual city result'
+      'empty manual city result',
+      'scene regeneration revokes old code',
+      'QR and NFC navigation without permissions',
+      'scene scan statistics',
+      'Wi-Fi denied without active order',
+      'Wi-Fi allowed by active order grant',
+      'Wi-Fi audit excludes password'
     ]
   }, null, 2));
 } finally {

backend/tests/store-access.test.mjs

@@ -0,0 +1,98 @@
+import assert from 'node:assert/strict';
+import { buildApp } from '../dist/app.js';
+import { signAccessToken } from '../dist/auth/jwt.js';
+import { StoreAccessError, StoreAccessRepository } from '../dist/stores/access-repository.js';
+
+const transactionCalls = [];
+const connection = {
+  async beginTransaction() { transactionCalls.push('begin'); },
+  async commit() { transactionCalls.push('commit'); },
+  async rollback() { transactionCalls.push('rollback'); },
+  release() { transactionCalls.push('release'); },
+  async execute(sql) {
+    if (sql.includes('FROM qipai_scene_codes') && sql.includes('code = ?')) {
+      return [[{
+        id: 1, tenantId: 7, targetType: 'ROOM', storeId: 11,
+        roomId: 31, generation: 1, scanCount: 0
+      }], []];
+    }
+    return [{ affectedRows: 1 }, []];
+  }
+};
+const repository = new StoreAccessRepository({
+  async getConnection() { return connection; },
+  async execute(sql) {
+    if (sql.includes('qipai_order_user_access')) return [[{ total: 0 }], []];
+    return [[], []];
+  }
+});
+const resolved = await repository.resolveScene({
+  code: 'abcdefghijklmnop', sourceType: 'NFC', traceId: 'trace',
+  ip: '127.0.0.1', userAgent: 'test'
+});
+assert.equal(resolved.page, '/pages/room/detail');
+assert.deepEqual(resolved.permissions, []);
+assert.ok(transactionCalls.includes('commit'));
+await assert.rejects(
+  () => repository.getWifi({
+    tenantId: '7', userId: '21',
+    access: { roles: ['CUSTOMER'], capabilities: [], storeIds: [] },
+    storeId: '11', traceId: 'trace', ip: '127.0.0.1', userAgent: 'test'
+  }),
+  (error) => error instanceof StoreAccessError && error.code === 'WIFI_ACCESS_FORBIDDEN'
+);
+
+const secret = 'test-only-jwt-secret-with-at-least-32-characters';
+const token = signAccessToken({
+  sub: '21', sid: '5c4d3af8-c63c-4edb-bf95-b84127bb3f6e',
+  tid: '7', aid: '9', rv: 1
+}, secret, 900);
+const app = await buildApp({
+  storeAccess: {
+    jwtSecret: secret,
+    authRepository: {
+      async validateSession() {
+        return {
+          id: '5c4d3af8-c63c-4edb-bf95-b84127bb3f6e',
+          tenantId: '7', platformAppId: '9', expiresAt: new Date(Date.now() + 60000),
+          user: {
+            id: '21', tenantId: '7', userType: 'STAFF', status: 'ACTIVE',
+            roleVersion: 1, nickname: '', avatarUrl: '', phone: ''
+          }
+        };
+      }
+    },
+    accessControl: {
+      async getAccessProfile() {
+        return { roles: ['TENANT_ADMIN'], capabilities: ['tenant.manage'], storeIds: [] };
+      }
+    },
+    repository: {
+      async regenerateScene() { return { sceneCodeId: '1', code: 'abcdefghijklmnop', generation: 1 }; },
+      async revokeScene() { return { sceneCodeId: '1', revoked: true }; },
+      async resolveScene() {
+        return {
+          targetType: 'STORE', storeId: '11', roomId: null,
+          page: '/pages/store/detail', permissions: []
+        };
+      },
+      async sceneStats() { return []; },
+      async getWifi() { return { ssid: 'QIPAI', password: '<test-only>' }; }
+    }
+  }
+});
+const generated = await app.inject({
+  method: 'POST', url: '/admin-api/scene-codes/regenerate',
+  headers: { authorization: `Bearer ${token}` },
+  payload: { targetType: 'STORE', storeId: '11' }
+});
+assert.equal(generated.statusCode, 201);
+const scan = await app.inject({
+  method: 'POST', url: '/app-api/scenes/resolve',
+  payload: { code: 'abcdefghijklmnop', sourceType: 'QRCODE' }
+});
+assert.equal(scan.statusCode, 200);
+assert.deepEqual(scan.json().data.permissions, []);
+await app.close();
+
+console.log('PASS: M03-D scene navigation has no door permission and Wi-Fi access is guarded.');