create-bubbles 0.1.26 → 0.1.27

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/seed/access-seed.service.ts

@@ -0,0 +1,183 @@
+import { Inject, Injectable, type OnModuleInit } from '@nestjs/common'
+import { DRIZZLE, type DrizzleDB } from '@/database/db.module'
+import {
+  accessBootstrap,
+  auditLogs,
+  cleanupTombstones,
+  companies,
+  menus,
+  menuVersions,
+  permissions,
+  projects,
+  rolePermissions,
+  roles,
+  userRoles,
+  users,
+} from '@/database/schema'
+import { and, eq, sql } from 'drizzle-orm'
+import type { AccessScope } from 'shared/types'
+import {
+  ACCESS_PAGE_CATALOG,
+  ACCESS_PERMISSION_CATALOG,
+  ACCESS_PROTECTED_ROUTE_KEYS,
+  getBuiltinPermissionKeys,
+  normalizeAccount,
+} from 'shared/utils'
+import { AppException } from '@/common/exceptions/app.exception'
+import { ACCESS_ERRORS } from '../access.errors'
+import { lockAccess, scopeColumns, scopeFilter, type AccessTx } from '../access.store'
+
+@Injectable()
+export class AccessSeedService implements OnModuleInit {
+  constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}
+  /** 服务启动时在权限写锁保护下同步权限目录、默认菜单和各作用域内置角色。 */
+  async onModuleInit() {
+    await this.db.transaction(async (tx) => {
+      await lockAccess(tx)
+      await this.sync(tx)
+    })
+  }
+
+  /**
+   * 幂等创建作用域内置管理员和普通成员角色，并补齐尚未清理的默认权限。
+   *
+   * 只追加缺失权限，发生追加时递增角色版本；清理墓碑标记的权限不会恢复。
+   * @returns 当前作用域的内置角色记录。
+   */
+  async ensureRoles(tx: AccessTx, scope: AccessScope) {
+    for (const builtin of ['administrator', 'member'] as const) {
+      await tx
+        .insert(roles)
+        .values({
+          ...scopeColumns(scope),
+          name: builtin === 'administrator' ? '内置管理员' : '内置普通成员',
+          builtin,
+        })
+        .onConflictDoNothing()
+    }
+    const found = await tx.select().from(roles).where(scopeFilter(scope))
+    const tombstones = new Set(
+      (await tx.select().from(cleanupTombstones)).map((t) => t.permissionKey),
+    )
+    for (const role of found.filter((r) => r.builtin)) {
+      const keys = getBuiltinPermissionKeys({
+        scopeType: scope.type,
+        builtin: role.builtin!,
+      }).filter((k) => !tombstones.has(k))
+      const current = await tx
+        .select()
+        .from(rolePermissions)
+        .where(eq(rolePermissions.roleId, role.id))
+      const additions = keys.filter((k) => !current.some((p) => p.permissionKey === k))
+      if (additions.length) {
+        await tx
+          .insert(rolePermissions)
+          .values(additions.map((permissionKey) => ({ roleId: role.id, permissionKey })))
+          .onConflictDoNothing()
+        await tx
+          .update(roles)
+          .set({ version: sql`${roles.version} + 1`, updatedAt: new Date() })
+          .where(eq(roles.id, role.id))
+      }
+    }
+    return found.filter((r) => r.builtin)
+  }
+
+  /**
+   * 将代码权限目录同步到数据库，补建菜单及各作用域内置角色，同时保留已有菜单配置。
+   *
+   * 清理墓碑中的权限不会重建；新增菜单时递增对应作用域的菜单版本。
+   */
+  async sync(tx: AccessTx) {
+    const tombstones = new Set(
+      (await tx.select().from(cleanupTombstones)).map((t) => t.permissionKey),
+    )
+    const catalog = ACCESS_PERMISSION_CATALOG.filter((p) => !tombstones.has(p.key))
+    for (const scope of ['platform', 'company', 'project'] as const)
+      await tx.insert(menuVersions).values({ scopeType: scope }).onConflictDoNothing()
+    for (const item of catalog)
+      await tx
+        .insert(permissions)
+        .values(item)
+        .onConflictDoUpdate({ target: permissions.key, set: item })
+    for (const item of catalog.filter((p) => !p.deprecated)) {
+      const [existing] = await tx.select().from(menus).where(eq(menus.permissionKey, item.key))
+      if (existing) continue
+      const [parent] = item.pagePermissionKey
+        ? await tx.select().from(menus).where(eq(menus.permissionKey, item.pagePermissionKey))
+        : []
+      const defaultIcon =
+        item.kind === 'page'
+          ? (ACCESS_PAGE_CATALOG.find((page) => page.routeKey === item.routeKey)?.icon ?? '')
+          : ''
+      await tx.insert(menus).values({
+        scopeType: item.scopeType,
+        type: item.kind,
+        name: item.title,
+        routeKey: item.routeKey,
+        permissionKey: item.key,
+        parentId: parent?.id ?? null,
+        icon: defaultIcon,
+        protected: (ACCESS_PROTECTED_ROUTE_KEYS as readonly string[]).includes(item.routeKey),
+        sort: catalog.indexOf(item),
+      })
+      await tx
+        .update(menuVersions)
+        .set({ version: sql`${menuVersions.version} + 1` })
+        .where(eq(menuVersions.scopeType, item.scopeType))
+    }
+    await this.ensureRoles(tx, { type: 'platform' })
+    for (const company of await tx.select({ id: companies.id }).from(companies))
+      await this.ensureRoles(tx, { type: 'company', companyId: company.id })
+    for (const project of await tx
+      .select({ id: projects.id, companyId: projects.companyId })
+      .from(projects))
+      await this.ensureRoles(tx, {
+        type: 'project',
+        companyId: project.companyId,
+        projectId: project.id,
+      })
+  }
+
+  /**
+   * 为有效账号执行首次平台管理员初始化，同步基础权限并写入初始化标记和审计记录。
+   *
+   * @param account - 待授予首位平台管理员身份的账号，会先进行规范化。
+   * @returns 初始化状态；相同账号重复调用可安全返回，其他账号再次初始化会被拒绝。
+   */
+  async initialize(account: string) {
+    return this.db.transaction(async (tx) => {
+      await lockAccess(tx)
+      const [user] = await tx
+        .select()
+        .from(users)
+        .where(and(eq(users.account, normalizeAccount(account)), eq(users.status, 'active')))
+        .for('share')
+      if (!user) throw new AppException(ACCESS_ERRORS.INVALID_MEMBER_ACCOUNT)
+      const [bootstrap] = await tx.select().from(accessBootstrap)
+      if (bootstrap && bootstrap.initializedAdminUserId !== user.id)
+        throw new AppException(ACCESS_ERRORS.ALREADY_INITIALIZED)
+      await this.sync(tx)
+      if (!bootstrap) {
+        const [role] = await tx
+          .select()
+          .from(roles)
+          .where(and(scopeFilter({ type: 'platform' }), eq(roles.builtin, 'administrator')))
+        await tx.insert(userRoles).values({ userId: user.id, roleId: role!.id })
+        await tx.insert(accessBootstrap).values({ id: 1, initializedAdminUserId: user.id })
+        await tx.insert(auditLogs).values({
+          actorUserId: user.id,
+          actorAccount: user.account,
+          actorName: user.name,
+          scopeType: 'platform',
+          action: 'access.initialize',
+          objectType: 'platform',
+          objectId: 'platform',
+          summary: { targetUserId: user.id },
+          requestId: crypto.randomUUID(),
+        })
+      }
+      return { initialized: true, account: user.account, alreadyInitialized: !!bootstrap }
+    })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/workspaces/workspaces.controller.ts

@@ -0,0 +1,28 @@
+import { Controller, Get, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy, Authenticated } from '@/common/decorators/access-policy.decorator'
+import { actor, scopeFor } from '@/modules/access/access-http'
+import { WorkspacesService } from './workspaces.service'
+
+@Controller()
+export class WorkspacesController {
+  constructor(private readonly workspacesService: WorkspacesService) {}
+
+  /** 为已登录用户返回可进入的工作空间及其管理员身份。 */
+  @Get('workspaces')
+  @Authenticated()
+  workspaces(@Req() req: FastifyRequest) {
+    return this.workspacesService.workspaces(actor(req))
+  }
+
+  /** 根据路由推导工作空间，返回该空间的用户权限、菜单和版本上下文。 */
+  @Get([
+    'platform/access',
+    'companies/:companyId/access',
+    'companies/:companyId/projects/:projectId/access',
+  ])
+  @AccessPolicy({ scope: 'route' })
+  context(@Req() req: FastifyRequest) {
+    return this.workspacesService.context({ actor: actor(req), scope: scopeFor(req) })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/workspaces/workspaces.service.ts

@@ -0,0 +1,94 @@
+import { Injectable } from '@nestjs/common'
+import { and, eq } from 'drizzle-orm'
+import { companies, companyMembers, projects, projectMembers, users } from '@/database/schema'
+import { AppException } from '@/common/exceptions/app.exception'
+import { AUTH_ERRORS } from '@/modules/auth/auth.errors'
+import { AccessService, type AccessActor } from '@/modules/access/access.service'
+import type { AccessScope, WorkspacesResult } from 'shared/types'
+
+@Injectable()
+export class WorkspacesService {
+  constructor(private readonly access: AccessService) {}
+
+  /** 校验用户对目标工作空间的访问资格，返回经过可见性过滤的菜单和有效权限上下文。 */
+  context(input: { actor: AccessActor; scope: AccessScope }) {
+    return this.access.read(input, async (_tx, access) => this.access.context(access))
+  }
+  /**
+   * 在一致性快照中列出有效账号可进入的平台、公司及项目工作空间。
+   *
+   * 仅包含启用的公司、项目及有效成员关系；公司管理员可进入所属公司的全部启用项目。
+   */
+  workspaces(actor: AccessActor): Promise<WorkspacesResult> {
+    return this.access.db.transaction(
+      /** 在同一快照内校验账号，汇总平台角色、有效成员关系及可继承的公司管理员身份。 */
+      async (tx) => {
+        const [user] = await tx
+          .select({ id: users.id, name: users.name, account: users.account, status: users.status })
+          .from(users)
+          .where(eq(users.id, actor.userId))
+        if (!user || user.status !== 'active') throw new AppException(AUTH_ERRORS.SESSION_INVALID)
+        const workspaces: WorkspacesResult['workspaces'] = []
+        if ((await this.access.roleAssignments(tx, { type: 'platform' }, user.id)).length)
+          workspaces.push({
+            scope: { type: 'platform' },
+            name: '平台管理',
+            administrator: (await this.access.isAdministrator(tx, { type: 'platform' }, user.id))
+              ? 'platform'
+              : null,
+          })
+        const memberships = await tx
+          .select({ company: companies })
+          .from(companyMembers)
+          .innerJoin(companies, eq(companies.id, companyMembers.companyId))
+          .where(
+            and(
+              eq(companyMembers.userId, user.id),
+              eq(companyMembers.status, 'active'),
+              eq(companies.status, 'active'),
+            ),
+          )
+        for (const { company } of memberships) {
+          const scope: AccessScope = { type: 'company', companyId: company.id }
+          const isAdmin = await this.access.isAdministrator(tx, scope, user.id)
+          workspaces.push({ scope, name: company.name, administrator: isAdmin ? 'company' : null })
+          const allProjects = await tx
+            .select()
+            .from(projects)
+            .where(and(eq(projects.companyId, company.id), eq(projects.status, 'active')))
+          const joined = await tx
+            .select()
+            .from(projectMembers)
+            .where(
+              and(
+                eq(projectMembers.companyId, company.id),
+                eq(projectMembers.userId, user.id),
+                eq(projectMembers.status, 'active'),
+              ),
+            )
+          for (const project of allProjects.filter(
+            (p) => isAdmin || joined.some((m) => m.projectId === p.id),
+          )) {
+            const projectScope: AccessScope = {
+              type: 'project',
+              companyId: company.id,
+              projectId: project.id,
+            }
+            workspaces.push({
+              scope: projectScope,
+              name: project.name,
+              companyName: company.name,
+              administrator: isAdmin
+                ? 'company'
+                : (await this.access.isAdministrator(tx, projectScope, user.id))
+                  ? 'project'
+                  : null,
+            })
+          }
+        }
+        return { user: { id: user.id, name: user.name, account: user.account }, workspaces }
+      },
+      { isolationLevel: 'repeatable read', accessMode: 'read only' },
+    )
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/access/workspaces/workspaces.validation.ts

@@ -0,0 +1,5 @@
+export {
+  createCompanySchema,
+  createProjectSchema,
+  updateProfileSchema as profileSchema,
+} from 'shared/utils'

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/audit/audit.controller.ts

@@ -0,0 +1,26 @@
+import { Controller, Get, Query, Req } from '@nestjs/common'
+import type { FastifyRequest } from 'fastify'
+import { AccessPolicy } from '@/common/decorators/access-policy.decorator'
+import { actor, scopeFor } from '@/modules/access/access-http'
+import { parse } from '@/modules/access/access.validation'
+import { AuditService } from './audit.service'
+import { auditSchema } from './audit.validation'
+
+@Controller([
+  'platform/audit-logs',
+  'companies/:companyId/audit-logs',
+  'companies/:companyId/projects/:projectId/audit-logs',
+])
+export class AuditController {
+  constructor(private readonly audit: AuditService) {}
+  /** 校验分页、操作者及时间筛选参数，读取路由对应作用域内的审计日志。 */
+  @Get()
+  @AccessPolicy({ scope: 'route', permission: '{scope}.audit.read' })
+  list(@Req() req: FastifyRequest, @Query() raw: unknown) {
+    return this.audit.list({
+      actor: actor(req),
+      scope: scopeFor(req),
+      query: parse(auditSchema, raw),
+    })
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/audit/audit.module.ts

@@ -0,0 +1,11 @@
+import { Module } from '@nestjs/common'
+import { AccessModule } from '../access/access.module'
+import { AuditController } from './audit.controller'
+import { AuditService } from './audit.service'
+
+@Module({
+  imports: [AccessModule],
+  controllers: [AuditController],
+  providers: [AuditService],
+})
+export class AuditModule {}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/audit/audit.service.ts

@@ -0,0 +1,74 @@
+import { Injectable } from '@nestjs/common'
+import { and, count, desc, eq, gte, lte } from 'drizzle-orm'
+import type { AccessScope, AuditQuery, AuditRecord, PageResult } from 'shared/types'
+import { auditLogs } from '@/database/schema'
+import { AccessService, type AccessActor } from '@/modules/access/access.service'
+import { pageWindow, searchSql, toScope } from '@/modules/access/access.store'
+
+@Injectable()
+export class AuditService {
+  constructor(private readonly access: AccessService) {}
+
+  /**
+   * 按当前作用域审计权限分页查询日志，支持操作、操作者、时间范围和关键词筛选。
+   *
+   * 平台仅查询平台日志，公司包含本公司及所属项目日志，项目仅查询该项目日志。
+   * @returns 按时间倒序排列的审计记录及分页信息。
+   */
+  list(input: {
+    actor: AccessActor
+    scope: AccessScope
+    query: AuditQuery
+  }): Promise<PageResult<AuditRecord>> {
+    const { actor, scope, query } = input
+    return this.access.read(
+      { actor, scope, permission: `${scope.type}.audit.read` },
+      /** 按平台、公司或项目构造日志范围，在同一快照内完成筛选、计数和分页。 */
+      async (tx) => {
+        const scopeCondition =
+          scope.type === 'platform'
+            ? eq(auditLogs.scopeType, 'platform')
+            : scope.type === 'company'
+              ? eq(auditLogs.companyId, scope.companyId)
+              : and(
+                  eq(auditLogs.companyId, scope.companyId),
+                  eq(auditLogs.projectId, scope.projectId),
+                  eq(auditLogs.scopeType, 'project'),
+                )
+        const { page, pageSize, offset } = pageWindow(query)
+        const condition = and(
+          scopeCondition,
+          query.action ? eq(auditLogs.action, query.action) : undefined,
+          query.actorId ? eq(auditLogs.actorUserId, query.actorId) : undefined,
+          query.from ? gte(auditLogs.createdAt, new Date(query.from)) : undefined,
+          query.to ? lte(auditLogs.createdAt, new Date(query.to)) : undefined,
+          searchSql([auditLogs.action, auditLogs.objectType, auditLogs.objectId], query.query),
+        )
+        const [total] = await tx.select({ value: count() }).from(auditLogs).where(condition)
+        const rows = await tx
+          .select()
+          .from(auditLogs)
+          .where(condition)
+          .orderBy(desc(auditLogs.createdAt), desc(auditLogs.id))
+          .limit(pageSize)
+          .offset(offset)
+        return {
+          page,
+          pageSize,
+          total: total!.value,
+          items: rows.map((r) => ({
+            id: r.id,
+            actor: { id: r.actorUserId, name: r.actorName, account: r.actorAccount },
+            scope: toScope(r),
+            action: r.action,
+            objectType: r.objectType,
+            objectId: r.objectId,
+            summary: r.summary,
+            requestId: r.requestId,
+            createdAt: r.createdAt.toISOString(),
+          })),
+        }
+      },
+    )
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/audit/audit.validation.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod'
+import { idSchema, pageSchema } from '@/modules/access/access.validation'
+
+export const auditSchema = pageSchema
+  .extend({
+    action: z.string().max(120).optional(),
+    actorId: idSchema.optional(),
+    from: z.iso.datetime().optional(),
+    to: z.iso.datetime().optional(),
+  })
+  .refine((v) => !v.from || !v.to || v.from <= v.to)

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/auth.controller.ts

@@ -1,4 +1,5 @@
 import { CurrentAuth } from '@/common/decorators/current-auth.decorator'
+import { Authenticated } from '@/common/decorators/access-policy.decorator'
 import { Public } from '@/common/decorators/public.decorator'
 import { Body, Controller, Get, Headers, HttpCode, HttpStatus, Post, Req } from '@nestjs/common'
 import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger'
@@ -6,6 +7,7 @@ import type { FastifyRequest } from 'fastify'
 import { CurrentUser } from 'shared/types'
 import { AuthService } from './auth.service'
 import { LoginDto } from './dto/login.dto'
+import { ChangePasswordDto } from './password/change-password.dto'
 import { RegisterDto } from './dto/register.dto'
 import type { CurrentAuthType } from './session/session.types'
 
@@ -14,6 +16,9 @@ import type { CurrentAuthType } from './session/session.types'
 export class AuthController {
   constructor(private readonly authService: AuthService) {}
 
+  /**
+   * 接收注册资料，返回新账号的公开信息。
+   */
   @Public()
   @ApiOperation({ summary: '注册' })
   @Post('register')
@@ -21,6 +26,9 @@ export class AuthController {
     return this.authService.register(body)
   }
 
+  /**
+   * 从 HTTP 请求提取登录来源，并创建或替换当前终端会话。
+   */
   @Public()
   @ApiOperation({ summary: '登录并创建 Redis Session' })
   @HttpCode(HttpStatus.OK)
@@ -32,6 +40,9 @@ export class AuthController {
     })
   }
 
+  /**
+   * 按 Authorization 请求头撤销当前终端的会话。
+   */
   @ApiBearerAuth('session')
   @ApiOperation({ summary: '退出当前端' })
   @Public()
@@ -41,9 +52,13 @@ export class AuthController {
     return this.authService.logout(authorization)
   }
 
+  /**
+   * 结合认证上下文与最新用户资料，返回当前用户及登录终端。
+   */
   @ApiBearerAuth('session')
   @ApiOperation({ summary: '使用 Session Token 获取当前用户资料' })
   @Get('me')
+  @Authenticated()
   async me(@CurrentAuth() auth: CurrentAuthType): Promise<CurrentUser> {
     const user = await this.authService.getCurrentUser(auth.userId)
 
@@ -52,4 +67,14 @@ export class AuthController {
       terminal: auth.terminal,
     }
   }
+
+  /** 根据当前会话身份修改本人密码，成功后该用户全部终端会话失效。 */
+  @ApiBearerAuth('session')
+  @ApiOperation({ summary: '修改本人密码并撤销全部终端会话' })
+  @Post('change-password')
+  @HttpCode(HttpStatus.OK)
+  @Authenticated()
+  changePassword(@CurrentAuth() auth: CurrentAuthType, @Body() body: ChangePasswordDto) {
+    return this.authService.changePassword(auth.userId, body)
+  }
 }

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/auth.errors.ts

@@ -29,6 +29,16 @@ export const AUTH_ERRORS = {
     publicMessage: '账号已存在',
     status: HttpStatus.CONFLICT,
   },
+  OLD_PASSWORD_INCORRECT: {
+    code: 'AUTH.OLD_PASSWORD_INCORRECT',
+    publicMessage: '旧密码错误',
+    status: HttpStatus.UNPROCESSABLE_ENTITY,
+  },
+  PASSWORD_REUSE_NOT_ALLOWED: {
+    code: 'AUTH.PASSWORD_REUSE_NOT_ALLOWED',
+    publicMessage: '新密码不能与旧密码相同',
+    status: HttpStatus.UNPROCESSABLE_ENTITY,
+  },
   FORBIDDEN: {
     code: 'AUTH.FORBIDDEN',
     publicMessage: '没有权限执行此操作',

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/auth.module.ts

@@ -21,6 +21,6 @@ import { SessionTokenService } from './session/session-token.service'
       useClass: SessionAuthGuard,
     },
   ],
-  exports: [SessionStoreService],
+  exports: [PasswordService, SessionStoreService],
 })
 export class AuthModule {}

package/template-vp-monorepo-react-nestjs/apps/server/src/modules/auth/auth.repository.ts

@@ -5,15 +5,27 @@ import { eq } from 'drizzle-orm'
 
 type CreateUserInput = Pick<typeof users.$inferInsert, 'name' | 'account' | 'passwordHash'>
 
+interface PasswordWriteContext {
+  passwordHash: string
+  /** 在当前用户行锁和事务中写入新摘要。 */
+  setPasswordHash: (passwordHash: string) => Promise<void>
+}
+
 @Injectable()
 export class AuthRepository {
   constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}
 
+  /**
+   * 按标准化账号查找完整用户记录，供密码校验使用；不存在时返回 null。
+   */
   async findByAccount(account: string) {
     const [user] = await this.db.select().from(users).where(eq(users.account, account)).limit(1)
     return user ?? null
   }
 
+  /**
+   * 按用户 ID 读取身份与状态字段，避免查询结果携带密码摘要。
+   */
   async findPublicById(userId: string) {
     const [user] = await this.db
       .select({
@@ -28,6 +40,9 @@ export class AuthRepository {
     return user ?? null
   }
 
+  /**
+   * 插入用户并返回记录；账号唯一键冲突时不写入并返回 null。
+   */
   async createUser(input: CreateUserInput) {
     const [user] = await this.db
       .insert(users)
@@ -37,4 +52,49 @@ export class AuthRepository {
       .returning()
     return user ?? null
   }
+
+  /**
+   * 在事务中对启用用户持有共享行锁，并把锁内的最新密码摘要交给回调。
+   * 登录须复核该摘要，避免在并发改密撤销后凭旧密码建立新会话。
+   * @returns 操作结果；用户不存在或已停用时返回 null。
+   */
+  withActiveUserLock<T>(userId: string, operation: (passwordHash: string) => Promise<T>) {
+    /** 在事务结束前保留共享行锁，保证回调执行期间账号状态及摘要不再变化。 */
+    return this.db.transaction(async (tx) => {
+      const [user] = await tx
+        .select({ status: users.status, passwordHash: users.passwordHash })
+        .from(users)
+        .where(eq(users.id, userId))
+        .for('share')
+      if (!user || user.status !== 'active') return null
+      return operation(user.passwordHash)
+    })
+  }
+
+  /**
+   * 以排他行锁读取本人账号的最新摘要，并在同一事务中执行密码更新及会话撤销。
+   * 回调抛错时数据库更新回滚；已成功的 Redis 撤销不会恢复。
+   */
+  withPasswordWriteLock<T>(
+    userId: string,
+    operation: (context: PasswordWriteContext) => Promise<T>,
+  ) {
+    return this.db.transaction(async (tx) => {
+      const [user] = await tx
+        .select({ status: users.status, passwordHash: users.passwordHash })
+        .from(users)
+        .where(eq(users.id, userId))
+        .for('update')
+      if (!user || user.status !== 'active') return null
+      return operation({
+        passwordHash: user.passwordHash,
+        setPasswordHash: async (passwordHash) => {
+          await tx
+            .update(users)
+            .set({ passwordHash, updatedAt: new Date() })
+            .where(eq(users.id, userId))
+        },
+      })
+    })
+  }
 }