feat(api): 用户前缀查找并入 displayName——成员添加可按姓名搜人（方案 A）

线上根因：V1.1 账号=手机号，运营按姓名搜索恒空（accountPrefix 仅匹配
account）。扩展为 account OR displayName 前缀（括号分组保资格过滤不被
短路），大小写敏感/激活过滤/account 升序语义不变；与管理列表 query 模式
对齐。契约描述同步。附 members-categories e2e 冷启动超时对齐 120s。

Co-Authored-By: Claude Code <noreply@anthropic.com>

services/api/src/admin/users-lookup.service.ts

@@ -71,6 +71,10 @@ export class UsersLookupService {
   /**
    * 前缀查询（契约 listAdminUsers 前缀模式）：激活资格用户、account 升序、
    * limit 截断；响应为统一 AdminUserList 形状（P4a）。
+   * 2026-09-29 方案 A：前缀匹配扩展为 **account OR displayName**——V1.1 同步
+   * 用户账号=手机号，运营按姓名搜人是自然预期（此前仅 account，姓名搜索恒空，
+   * 线上成员添加「关联不到用户」根因）；与管理列表 query 模式的 OR displayName
+   * 对齐。大小写敏感（bin 校对）与资格过滤对两列同样生效。
    */
   async lookup(
     accountPrefix: string,
@@ -78,11 +82,13 @@ export class UsersLookupService {
   ): Promise<AdminUserListResponse> {
     const pattern = `${escapeLikePrefix(accountPrefix)}%`;
     // 参数经 $queryRaw 模板绑定（无拼接注入面）；LIMIT ? 为 MySQL 合法占位。
+    // OR 两列必须括号分组——否则资格过滤会被短路。
     const rows = await this.prisma.$queryRaw<AdminUserRow[]>`
       SELECT id, account, displayName, role, sourceStatus, localLocked,
              credentialStatus, locale, createdAt
       FROM users
-      WHERE account LIKE ${pattern} ESCAPE '!'
+      WHERE (account LIKE ${pattern} ESCAPE '!'
+             OR displayName LIKE ${pattern} ESCAPE '!')
         AND credentialStatus = 'active'
         AND sourceStatus <> 'disabled'
         AND localLocked = false

services/api/test/members-categories.e2e-spec.ts

@@ -14,6 +14,10 @@ import { randomBytes } from 'node:crypto';
 import { type INestApplication } from '@nestjs/common';
 import { Test } from '@nestjs/testing';
 import request from 'supertest';
+
+// 冷 infra（Docker 重启后）下 beforeAll 引导可超 jest 缺省 5s——对齐
+// 同目录其它 e2e 的 120s（2026-09-29 两次冷启动误报教训）。
+jest.setTimeout(120_000);
 import { PrismaClient } from '@photo/db-cn';
 import { ErrorCodes } from '@photo/contracts';
 import { AppCnModule } from '../src/app-cn.module';

services/api/test/users-lookup.e2e-spec.ts

@@ -197,6 +197,38 @@ describe('账号查询 GET /admin/users (e2e)', () => {
     expect(percent.body.items).toEqual([]);
   });
 
+  // displayName 前缀并入（2026-09-29 方案 A：运营按姓名搜人——账号=手机号下
+  // 姓名是运营唯一记得的标识；管理列表 query 模式此前已 OR displayName，
+  // 前缀模式对齐）。语义：account 前缀 OR displayName 前缀，资格过滤/
+  // account 升序/大小写敏感（bin 校对对两列同样生效）不变。
+  it('displayName 前缀命中（account 不匹配也可查）；两列命中并集按 account 升序', async () => {
+    const byName = await lookup(staffToken, { accountPrefix: '爱丽' });
+    expect(byName.status).toBe(200);
+    expect(byName.body.items).toEqual([
+      expect.objectContaining({ id: aliceId, account: 'alice', displayName: '爱丽' }),
+    ]);
+
+    // 前缀同时命中两列的多个用户：'批量' 命中 12 个 zz-look-* 的姓名，
+    // account 升序 + limit 截断（limit:5 → 01..05）。
+    const paged = await lookup(staffToken, { accountPrefix: '批量', limit: 5 });
+    expect(paged.status).toBe(200);
+    expect(paged.body.items.map((i: { account: string }) => i.account)).toEqual([
+      'zz-look-01', 'zz-look-02', 'zz-look-03', 'zz-look-04', 'zz-look-05',
+    ]);
+  });
+
+  it('displayName 命中同样受激活资格过滤（停用/待激活/锁定经姓名也查不到）', async () => {
+    const disabled = await lookup(staffToken, { accountPrefix: '停用' });
+    expect(disabled.status).toBe(200);
+    expect(disabled.body.items).toEqual([]);
+    const pending = await lookup(staffToken, { accountPrefix: '待激活' });
+    expect(pending.status).toBe(200);
+    expect(pending.body.items).toEqual([]);
+    const locked = await lookup(staffToken, { accountPrefix: '锁定' });
+    expect(locked.status).toBe(200);
+    expect(locked.body.items).toEqual([]);
+  });
+
   it('accountPrefix 边界：缺失 → 双模式分流（staff 403 / admin 200 管理列表）；1/65 字符 → 400；64 → 200 空', async () => {
     // Task 6 起缺失 accountPrefix 进入管理列表模式（仅 admin）：staff 无前缀
     // → 403 AUTH_FORBIDDEN；admin → 200 管理列表（全量用户，含非激活态——