create-bubbles 0.1.22 → 0.1.24

package/template-vp-monorepo-react-nestjs/apps/server/src/common/filters/global-exception.filter.ts

@@ -0,0 +1,384 @@
+import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Logger,
+} from '@nestjs/common'
+import { HttpAdapterHost } from '@nestjs/core'
+import { FastifyReply, FastifyRequest } from 'fastify'
+import { ZodSerializationException, ZodValidationException } from 'nestjs-zod'
+import { ApiErrorDetail, ApiFailure } from 'shared/types'
+import { ZodError } from 'zod'
+import { COMMON_ERRORS } from '../error/common.error'
+import { AppException } from '../exceptions/app.exception'
+
+interface PublicHttpError {
+  readonly code: string
+  readonly message: string
+}
+
+const MAX_DETAIL_COUNT = 20
+const MAX_DETAIL_PATH_LENGTH = 200
+/**
+ * 错误响应体的 details[number].code 的最长长度限制
+ */
+const MAX_DETAIL_CODE_LENGTH = 80
+const MAX_PUBLIC_MESSAGE_LENGTH = 300
+const MAX_LOG_MESSAGE_LENGTH = 1000
+const MAX_LOG_FRAME_LENGTH = 600
+const MAX_LOG_STACK_FRAMES = 12
+
+interface NormalizedFailure {
+  readonly status: number
+  readonly body: ApiFailure
+  readonly cause?: unknown
+  readonly bearerChallenge?: boolean
+}
+
+const PUBLIC_HTTP_ERRORS: Readonly<Record<number, PublicHttpError>> = {
+  [HttpStatus.BAD_REQUEST]: {
+    code: 'COMMON.BAD_REQUEST',
+    message: '请求内容无效',
+  },
+  [HttpStatus.UNAUTHORIZED]: {
+    code: 'COMMON.UNAUTHORIZED',
+    message: '身份认证失败',
+  },
+  [HttpStatus.FORBIDDEN]: {
+    code: 'COMMON.FORBIDDEN',
+    message: '没有权限执行此操作',
+  },
+  [HttpStatus.NOT_FOUND]: {
+    code: 'COMMON.NOT_FOUND',
+    message: '请求的资源不存在',
+  },
+  [HttpStatus.METHOD_NOT_ALLOWED]: {
+    code: 'COMMON.METHOD_NOT_ALLOWED',
+    message: '请求方法不受支持',
+  },
+  [HttpStatus.CONFLICT]: {
+    code: 'COMMON.CONFLICT',
+    message: '当前资源状态存在冲突',
+  },
+  [HttpStatus.PAYLOAD_TOO_LARGE]: {
+    code: 'COMMON.PAYLOAD_TOO_LARGE',
+    message: '请求内容过大',
+  },
+  [HttpStatus.UNSUPPORTED_MEDIA_TYPE]: {
+    code: 'COMMON.UNSUPPORTED_MEDIA_TYPE',
+    message: '请求内容类型不受支持',
+  },
+  [HttpStatus.UNPROCESSABLE_ENTITY]: {
+    code: 'COMMON.UNPROCESSABLE_CONTENT',
+    message: '请求内容无法处理',
+  },
+  [HttpStatus.TOO_MANY_REQUESTS]: {
+    code: 'COMMON.TOO_MANY_REQUESTS',
+    message: '请求过于频繁，请稍后重试',
+  },
+}
+
+function cleanPublicText(value: unknown, maxLength: number): string {
+  if (typeof value !== 'string') {
+    return ''
+  }
+
+  // 这段代码是在把字符串中的“不可见控制字符和换行符”全部替换成空格：
+  // \u0000-\u001F：ASCII 控制字符，包括换行 \n、回车 \r、Tab 等。
+  // \u007F-\u009F：其他不可见控制字符。
+  // \u2028：Unicode 行分隔符。
+  // \u2029：Unicode 段落分隔符。
+  return (
+    value
+      // oxlint-disable-next-line no-control-regex
+      .replace(/[\u0000-\u001F\u007F-\u009F\u2028\u2029]/g, ' ')
+      .trim()
+      .slice(0, maxLength)
+  )
+}
+
+function cleanDetailCode(value: unknown): string {
+  const code = cleanPublicText(value, MAX_DETAIL_CODE_LENGTH)
+  if (/^[A-Za-z][A-Za-z0-9._-]*$/.test(code)) {
+    return code
+  }
+  return 'invalid'
+}
+
+function normalizeDetails(
+  details: readonly ApiErrorDetail[] | undefined,
+): ApiErrorDetail[] | undefined {
+  const normalized = details?.slice(0, MAX_DETAIL_COUNT).map((detail) => {
+    const path = cleanPublicText(detail.path, MAX_DETAIL_PATH_LENGTH)
+    const message = cleanPublicText(detail.message, MAX_PUBLIC_MESSAGE_LENGTH) || '请求内容无效'
+
+    return {
+      ...(path ? { path } : {}),
+      code: cleanDetailCode(detail.code),
+      message,
+    }
+  })
+  return normalized?.length ? normalized : undefined
+}
+
+function normalizeStatus(value: unknown): number {
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    return HttpStatus.INTERNAL_SERVER_ERROR
+  }
+  if (value < 400 || value > 599) {
+    return HttpStatus.INTERNAL_SERVER_ERROR
+  }
+
+  return value
+}
+
+/**
+ * 对日志文本进行脱敏处理
+ * @param value 日志文本
+ * @param maxLength 最大长度
+ * @returns 脱敏后的日志文本
+ */
+function sanitizeLogText(value: string, maxLength: number): string {
+  return value
+    .replace(/[\u0000-\u001F\u007F\u2028\u2029]/g, ' ')
+    .replace(/\b([a-z][a-z0-9+.-]*:\/\/)([^@\s/]+)@/gi, '$1[REDACTED]@')
+    .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, '$1 [REDACTED]')
+    .replace(
+      /([?&](?:password|passwd|pwd|token|access[_-]?token|refresh[_-]?token|api[_-]?key|secret|client[_-]?secret)=)[^&#\s]*/gi,
+      '$1[REDACTED]',
+    )
+    .replace(
+      /(["']?)(authorization|proxy-authorization|cookie|set-cookie)\1\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^,}\]]+)/gi,
+      '$1$2$1=[REDACTED]',
+    )
+    .replace(
+      /(["']?)(password|passwd|pwd|token|access[_-]?token|refresh[_-]?token|api[_-]?key|x-api-key|secret|client[_-]?secret|database[_-]?url|redis[_-]?url|connection[_-]?string|dsn)\1\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;}\]]+)/gi,
+      '$1$2$1=[REDACTED]',
+    )
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, maxLength)
+}
+/**
+ * /u2028 行分隔符
+ * /u2029 段落分隔符
+ * @param error
+ * @returns
+ */
+function sanitizeStackFrame(error: Error): string[] | undefined {
+  if (!error.stack || /[\r\n\u2028\u2029]/.test(error.message)) {
+    return undefined
+  }
+
+  const frames = error.stack
+    .split(/\r?\n/)
+    .slice(1)
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('at '))
+    .slice(0, MAX_LOG_STACK_FRAMES)
+    .map((line) => sanitizeLogText(line, MAX_LOG_FRAME_LENGTH))
+    .filter(Boolean)
+  return frames.length ? frames : undefined
+}
+
+function serializeError(value: unknown, depth = 0): Record<string, unknown> {
+  if (!(value instanceof Error)) {
+    return {
+      type: typeof value,
+    }
+  }
+
+  const stackFrames = sanitizeStackFrame(value)
+  const result: Record<string, unknown> = {
+    name: sanitizeLogText(value.name, 120) || 'Error',
+    message: sanitizeLogText(value.message, MAX_LOG_MESSAGE_LENGTH),
+    ...(stackFrames ? { stackFrames } : {}),
+  }
+  if (depth < 2 && value.cause !== undefined) {
+    result.cause = serializeError(value.cause, depth + 1)
+  }
+  return result
+}
+
+@Catch()
+export class GlobalExceptionFilter implements ExceptionFilter {
+  private readonly logger = new Logger(GlobalExceptionFilter.name)
+
+  constructor(private readonly adapterHost: HttpAdapterHost) {}
+
+  private getZodDetails(exception: ZodValidationException): ApiErrorDetail[] | undefined {
+    const zodError = exception.getZodError()
+
+    if (!(zodError instanceof ZodError)) {
+      return undefined
+    }
+
+    const details = zodError.issues.slice(0, MAX_DETAIL_COUNT).map((issue) => {
+      const path = cleanPublicText(issue.path.map(String).join('.'), MAX_DETAIL_PATH_LENGTH)
+      const message = cleanPublicText(issue.message, MAX_PUBLIC_MESSAGE_LENGTH) || '请求内容无效'
+
+      return {
+        ...(path ? { path } : {}),
+        code: cleanDetailCode(issue.code),
+        message,
+      }
+    })
+    return details.length ? details : undefined
+  }
+
+  private normalizeLegacyHttpException(exception: HttpException): NormalizedFailure {
+    const status = normalizeStatus(exception.getStatus())
+
+    if (status >= 500) {
+      const serviceUnavailabel =
+        status === HttpStatus.BAD_GATEWAY ||
+        status === HttpStatus.SERVICE_UNAVAILABLE ||
+        status === HttpStatus.GATEWAY_TIMEOUT
+
+      return {
+        status,
+        body: serviceUnavailabel
+          ? {
+              code: COMMON_ERRORS.SERVICE_UNAVAILABLE.code,
+              message: COMMON_ERRORS.SERVICE_UNAVAILABLE.publicMessage,
+            }
+          : {
+              code: COMMON_ERRORS.INTERNAL_SERVER_ERROR.code,
+              message: COMMON_ERRORS.INTERNAL_SERVER_ERROR.publicMessage,
+            },
+        cause: exception,
+      }
+    }
+
+    const publicError = PUBLIC_HTTP_ERRORS[status] ?? {
+      code: 'COMMON.HTTP_' + status,
+      message: '请求处理失败',
+    }
+    return {
+      status,
+      body: publicError,
+      bearerChallenge: status === HttpStatus.UNAUTHORIZED,
+    }
+  }
+
+  private normalize(exception: unknown): NormalizedFailure {
+    if (exception instanceof ZodSerializationException) {
+      return {
+        status: HttpStatus.INTERNAL_SERVER_ERROR,
+        body: {
+          code: COMMON_ERRORS.INTERNAL_SERVER_ERROR.code,
+          message: COMMON_ERRORS.INTERNAL_SERVER_ERROR.publicMessage,
+        },
+        cause: exception.getZodError() ?? exception,
+      }
+    }
+
+    if (exception instanceof ZodValidationException) {
+      const details = this.getZodDetails(exception)
+
+      return {
+        status: COMMON_ERRORS.VALIDATION_FAILED.status,
+        body: {
+          code: COMMON_ERRORS.VALIDATION_FAILED.code,
+          message: COMMON_ERRORS.VALIDATION_FAILED.publicMessage,
+          ...(details?.length ? { details } : {}),
+        },
+      }
+    }
+
+    if (exception instanceof AppException) {
+      const status = normalizeStatus(exception.getStatus())
+      const details = normalizeDetails(exception.details)
+      const message =
+        cleanPublicText(exception.definition.publicMessage, MAX_PUBLIC_MESSAGE_LENGTH) ||
+        '请求处理失败'
+      return {
+        status,
+        body: {
+          code: exception.definition.code,
+          message,
+          ...(details?.length ? { details } : {}),
+        },
+        cause: status >= 500 ? (exception.cause ?? exception) : undefined,
+        bearerChallenge: exception.definition.bearerChallenge,
+      }
+    }
+
+    if (exception instanceof HttpException) {
+      return this.normalizeLegacyHttpException(exception)
+    }
+
+    return {
+      status: HttpStatus.INTERNAL_SERVER_ERROR,
+      body: {
+        code: COMMON_ERRORS.INTERNAL_SERVER_ERROR.code,
+        message: COMMON_ERRORS.INTERNAL_SERVER_ERROR.publicMessage,
+      },
+      cause: exception,
+    }
+  }
+
+  private logServerFailure(
+    exception: unknown,
+    normalized: NormalizedFailure,
+    request: FastifyRequest,
+    requestId: string,
+  ): void {
+    const route = request.routeOptions?.url ?? 'unmatched'
+    const cause = normalized.cause ?? exception
+
+    this.logger.error({
+      event: 'http_request_failed',
+      requestId,
+      method: request.method,
+      route,
+      status: normalized.status,
+      code: normalized.body.code,
+      error: serializeError(cause),
+    })
+  }
+
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const http = host.switchToHttp()
+    const request = http.getRequest<FastifyRequest>()
+    const response = http.getResponse<FastifyReply>()
+    const requestId = String(request.id)
+    const normalized = this.normalize(exception)
+    const { httpAdapter } = this.adapterHost
+
+    // 只记录服务器错误 业务错误不记录
+    if (normalized.status >= 500) {
+      this.logServerFailure(exception, normalized, request, requestId)
+    }
+
+    // 如果响应头已经被发送了 则直接结束响应 不再进行后面发的处理
+    if (httpAdapter.isHeadersSent(response)) {
+      httpAdapter.end(response)
+      return
+    }
+
+    httpAdapter.setHeader(response, 'x-request-id', requestId)
+
+    /** 如果是未授权错误 则添加WWW-Authenticate 头 相当于告诉客户 请使用Bearer 认证
+     * 为什么使用 normalized.bearerChallenge 而不是 normalized.status === HttpStatus.UNAUTHORIZED
+     * 因为 normalized.status === HttpStatus.UNAUTHORIZED 只是告诉客户 授权有问题
+     * 以下情况 bearerChallenge 为 false
+     * 账号被禁用/锁定、权限不足、API Key 认证失败 、Basic Auth 失败、IP / 网络层拦截、Session/Cookie 失效
+     * 为true 的场景
+     * 应该设为 true 的场景
+      异常类型	原因	为什么需要 Bearer 质询
+      Token 缺失	请求头没有 Authorization	客户端需要知道“这里要传 Bearer Token”
+      Token 格式错误	不是合法的 JWT / 签名不对	客户端可能传错了 Token 类型或损坏了
+      Token 过期	exp 时间已过	客户端需要用 refresh_token 换取新 Token
+      Token 签发者/受众不匹配	iss / aud 校验失败	客户端用了错误环境的 Token
+      Token 被吊销	在黑名单 / 撤销列表中	客户端需要重新获取 Token
+     */
+    if (normalized.bearerChallenge) {
+      httpAdapter.setHeader(response, 'www-authenticate', 'Bearer realm="api"')
+    }
+
+    httpAdapter.reply(response, normalized.body, normalized.status)
+  }
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/common/openapi/response-headers.ts

@@ -0,0 +1,9 @@
+export const REQUEST_ID_RESPONSE_HEADERS = {
+  'X-Request-Id': {
+    description: '服务端生成的请求关联 ID',
+    schema: {
+      type: 'string',
+      format: 'uuid',
+    },
+  },
+}

package/template-vp-monorepo-react-nestjs/apps/server/src/config/index.ts

@@ -2,4 +2,4 @@ export { default as appConfig } from './app.config'
 export { default as databaseConfig } from './database.config'
 export { default as llmConfig } from './llm.config'
 export { default as redisConfig } from './redis.config'
-export { default as authConfig } from './auth.config'
+export { default as sessionConfig } from './session.config'

package/template-vp-monorepo-react-nestjs/apps/server/src/config/session.config.ts

@@ -0,0 +1,36 @@
+import { registerAs } from '@nestjs/config'
+
+function readPositiveInteger(name: string, fallback: number) {
+  const value = Number.parseInt(process.env[name] ?? String(fallback), 10)
+
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`)
+  }
+  return value
+}
+
+export default registerAs('session', () => {
+  const tokenPepper = process.env.SESSION_TOKEN_PEPPER
+  /**
+   * 没有置换的情况下的过期时间 2个小时
+   */
+  const idleTtlSeconds = readPositiveInteger('SESSION_IDLE_TTL_SECONDS', 7200)
+  /**
+   * 绝对过期时间7天
+   */
+  const absoluteTtlSeconds = readPositiveInteger('SESSION_ABSOLUTE_TTL_SECONDS', 604800)
+
+  if (!tokenPepper || tokenPepper.length < 32) {
+    throw new Error('SESSION_TOKEN_PEPPER must contain at least 32 characters')
+  }
+
+  if (absoluteTtlSeconds <= idleTtlSeconds) {
+    throw new Error('SESSION_ABSOLUTE_TTL_SECONDS must be greater than idle TTL')
+  }
+
+  return {
+    tokenPepper,
+    idleTtlMs: +idleTtlSeconds * 1000,
+    absoluteTtlMs: +absoluteTtlSeconds * 1000,
+  }
+})

package/template-vp-monorepo-react-nestjs/apps/server/src/database/schema.ts

@@ -1,14 +1,13 @@
-import { pgEnum } from 'drizzle-orm/pg-core'
-import { pgTable, serial, varchar, timestamp } from 'drizzle-orm/pg-core'
+import { pgEnum, pgTable, timestamp, uuid, varchar } from 'drizzle-orm/pg-core'
 
-export const useStatusEnum = pgEnum('user_status', ['active', 'locked', 'disabled'])
-
-export const authSessionStatusEnum = pgEnum('auth_session_status', ['active', 'revoked'])
+export const userStatusEnum = pgEnum('user_status', ['active', 'locked', 'disabled'])
 
 export const users = pgTable('users', {
-  id: serial('id').primaryKey(),
+  id: uuid('id').defaultRandom().primaryKey(),
   name: varchar('name', { length: 100 }).notNull(),
-  email: varchar('email', { length: 255 }).notNull().unique(),
-  password: varchar('password', { length: 255 }).notNull(),
+  account: varchar('account', { length: 32 }).notNull().unique(),
+  passwordHash: varchar('password_hash', { length: 255 }).notNull(),
+  status: userStatusEnum('status').default('active').notNull(),
   createdAt: timestamp('create_at').defaultNow().notNull(),
+  updatedAt: timestamp('update_at', { withTimezone: true }).defaultNow().notNull(),
 })

package/template-vp-monorepo-react-nestjs/apps/server/src/main.ts

@@ -1,21 +1,38 @@
-import { NestFactory } from '@nestjs/core'
 import { AppModule } from '@/app.module'
 import { logNetworkUrls } from '@/utils/server-address'
-import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify'
+import { ConsoleLogger, Logger } from '@nestjs/common'
+import { NestFactory } from '@nestjs/core'
+import { type NestFastifyApplication } from '@nestjs/platform-fastify'
 import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'
 import { cleanupOpenApiDoc } from 'nestjs-zod'
-import fastifyCookie from '@fastify/cookie'
+import { createFastifyAdapter } from './common/adapters/fastify.adapter'
 
 async function bootstrap() {
-  const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter())
-
-  await app.register(fastifyCookie)
+  const app = await NestFactory.create<NestFastifyApplication>(AppModule, createFastifyAdapter(), {
+    logger: new ConsoleLogger({
+      json: process.env.NODE_ENV === 'production',
+      colors: process.env.NODE_ENV === 'development',
+    }),
+  })
+  app.enableCors({
+    origin: ['*'],
+    allowedHeaders: ['Content-Type', 'Authorization', 'X-Company-Id'],
+    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+    exposedHeaders: ['X-Request-Id', 'WWW-Authenticate', 'Retry-After'],
+  })
 
   const config = new DocumentBuilder()
     .setTitle('前后端模板 API')
     .setDescription('接口文档')
     .setVersion('1.0')
-    .addBearerAuth() // 用 JWT 就留着,不用可以删
+    .addBearerAuth(
+      {
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'Opaque Session Token',
+      },
+      'session',
+    ) // 用 JWT 就留着,不用可以删
     .build()
 
   // 生成openAPI 文档
@@ -31,4 +48,8 @@ async function bootstrap() {
   logNetworkUrls(port)
 }
 
-void bootstrap()
+void bootstrap().catch((cause: unknown) => {
+  const logger = new Logger('Bootstrap')
+  logger.error('Server boostrap failed', cause instanceof Error ? cause.stack : undefined)
+  process.exitCode = 1
+})

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

@@ -0,0 +1,55 @@
+import { CurrentAuth } from '@/common/decorators/current-auth.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'
+import type { FastifyRequest } from 'fastify'
+import { CurrentUser } from 'shared/types'
+import { AuthService } from './auth.service'
+import { LoginDto } from './dto/login.dto'
+import { RegisterDto } from './dto/register.dto'
+import type { CurrentAuthType } from './session/session.types'
+
+@ApiTags('认证')
+@Controller('auth')
+export class AuthController {
+  constructor(private readonly authService: AuthService) {}
+
+  @Public()
+  @ApiOperation({ summary: '注册' })
+  @Post('register')
+  register(@Body() body: RegisterDto) {
+    return this.authService.register(body)
+  }
+
+  @Public()
+  @ApiOperation({ summary: '登录并创建 Redis Session' })
+  @HttpCode(HttpStatus.OK)
+  @Post('login')
+  login(@Body() body: LoginDto, @Req() request: FastifyRequest) {
+    return this.authService.login(body, {
+      ip: request.ip,
+      userAgent: request.headers['user-agent'] ?? '',
+    })
+  }
+
+  @ApiBearerAuth('session')
+  @ApiOperation({ summary: '退出当前端' })
+  @Public()
+  @HttpCode(HttpStatus.OK)
+  @Post('logout')
+  logout(@Headers('authorization') authorization: string | undefined) {
+    return this.authService.logout(authorization)
+  }
+
+  @ApiBearerAuth('session')
+  @ApiOperation({ summary: '使用 Session Token 获取当前用户资料' })
+  @Get('me')
+  async me(@CurrentAuth() auth: CurrentAuthType): Promise<CurrentUser> {
+    const user = await this.authService.getCurrentUser(auth.userId)
+
+    return {
+      ...user,
+      terminal: auth.terminal,
+    }
+  }
+}

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

@@ -0,0 +1,42 @@
+import type { AppErrorDefinition } from '@/common/exceptions/app.exception'
+import { HttpStatus } from '@nestjs/common'
+
+export const AUTH_ERRORS = {
+  SESSION_TOKEN_MISSING: {
+    code: 'AUTH.SESSION_TOKEN_MISSING',
+    publicMessage: '缺少有效的登录 Token',
+    status: HttpStatus.UNAUTHORIZED,
+    bearerChallenge: true,
+  },
+  SESSION_INVALID: {
+    code: 'AUTH.SESSION_INVALID',
+    publicMessage: '登录已失效，请重新登录',
+    status: HttpStatus.UNAUTHORIZED,
+    bearerChallenge: true,
+  },
+  CONTEXT_MISSING: {
+    code: 'AUTH.CONTEXT_MISSING',
+    publicMessage: '服务器内部错误',
+    status: HttpStatus.INTERNAL_SERVER_ERROR,
+  },
+  INVALID_CREDENTIALS: {
+    code: 'AUTH.INVALID_CREDENTIALS',
+    publicMessage: '账号或密码错误',
+    status: HttpStatus.UNPROCESSABLE_ENTITY,
+  },
+  ACCOUNT_ALREADY_EXISTS: {
+    code: 'AUTH.ACCOUNT_ALREADY_EXISTS',
+    publicMessage: '账号已存在',
+    status: HttpStatus.CONFLICT,
+  },
+  FORBIDDEN: {
+    code: 'AUTH.FORBIDDEN',
+    publicMessage: '没有权限执行此操作',
+    status: HttpStatus.FORBIDDEN,
+  },
+  SERVICE_UNAVAILABLE: {
+    code: 'AUTH.SERVICE_UNAVAILABLE',
+    publicMessage: '登录服务暂时不可用，请稍后重试',
+    status: HttpStatus.SERVICE_UNAVAILABLE,
+  },
+} as const satisfies Record<string, AppErrorDefinition>

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

@@ -0,0 +1,26 @@
+import { Module } from '@nestjs/common'
+import { APP_GUARD } from '@nestjs/core'
+import { AuthController } from './auth.controller'
+import { AuthRepository } from './auth.repository'
+import { AuthService } from './auth.service'
+import { SessionAuthGuard } from './guards/session-auth.guard'
+import { PasswordService } from './password.service'
+import { SessionStoreService } from './session/session-store.service'
+import { SessionTokenService } from './session/session-token.service'
+
+@Module({
+  controllers: [AuthController],
+  providers: [
+    AuthRepository,
+    AuthService,
+    PasswordService,
+    SessionTokenService,
+    SessionStoreService,
+    {
+      provide: APP_GUARD,
+      useClass: SessionAuthGuard,
+    },
+  ],
+  exports: [SessionStoreService],
+})
+export class AuthModule {}

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

@@ -0,0 +1,40 @@
+import { DRIZZLE, type DrizzleDB } from '@/database/db.module'
+import { users } from '@/database/schema'
+import { Inject, Injectable } from '@nestjs/common'
+import { eq } from 'drizzle-orm'
+
+type CreateUserInput = Pick<typeof users.$inferInsert, 'name' | 'account' | 'passwordHash'>
+
+@Injectable()
+export class AuthRepository {
+  constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}
+
+  async findByAccount(account: string) {
+    const [user] = await this.db.select().from(users).where(eq(users.account, account)).limit(1)
+    return user ?? null
+  }
+
+  async findPublicById(userId: string) {
+    const [user] = await this.db
+      .select({
+        id: users.id,
+        account: users.account,
+        name: users.name,
+        status: users.status,
+      })
+      .from(users)
+      .where(eq(users.id, userId))
+      .limit(1)
+    return user ?? null
+  }
+
+  async createUser(input: CreateUserInput) {
+    const [user] = await this.db
+      .insert(users)
+      .values(input)
+      // 处理账号重复情况 ，不插入重复账号
+      .onConflictDoNothing({ target: users.account })
+      .returning()
+    return user ?? null
+  }
+}