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

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();
+    }
+  }
+}