create-bubbles 0.1.25 → 0.1.27

package/template-vp-monorepo-react-nestjs/apps/server/drizzle/meta/_journal.json

@@ -0,0 +1,48 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1786876205265,
+      "tag": "0000_military_colonel_america",
+      "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1787991631984,
+      "tag": "0001_loud_siren",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1788964645628,
+      "tag": "0002_enterprise_access",
+      "breakpoints": true
+    },
+    {
+      "idx": 3,
+      "version": "7",
+      "when": 1789548181117,
+      "tag": "0003_cute_killmonger",
+      "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1789622665438,
+      "tag": "0004_company-member-invitations",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1789790400000,
+      "tag": "0005_menu_svg_icons",
+      "breakpoints": true
+    }
+  ]
+}

package/template-vp-monorepo-react-nestjs/apps/server/drizzle/rollback/0003_organization_backfill.sql

@@ -0,0 +1,32 @@
+-- 该脚本只回滚 0003 迁移创建的空组织树，不回滚表结构。
+-- 如任一批次树已经包含组织单元或成员关系，脚本会整体终止并要求人工审阅。
+DO $$
+BEGIN
+	IF EXISTS (
+		SELECT 1
+		FROM "organization_trees" AS tree
+		WHERE tree."backfill_batch_key" = 'organization-v1-20260916'
+			AND (
+				EXISTS (
+					SELECT 1
+					FROM "organization_units" AS unit
+					WHERE unit."tree_id" = tree."id"
+				)
+				OR EXISTS (
+					SELECT 1
+					FROM "company_organization_unit_members" AS relation
+					WHERE relation."tree_id" = tree."id"
+				)
+				OR EXISTS (
+					SELECT 1
+					FROM "project_organization_unit_members" AS relation
+					WHERE relation."tree_id" = tree."id"
+				)
+			)
+	) THEN
+		RAISE EXCEPTION '拒绝自动回滚：organization-v1-20260916 批次中已有组织单元或业务引用，请人工审阅';
+	END IF;
+
+	DELETE FROM "organization_trees"
+	WHERE "backfill_batch_key" = 'organization-v1-20260916';
+END $$;

package/template-vp-monorepo-react-nestjs/apps/server/package.json

@@ -11,24 +11,29 @@
     "dev": "nest start --watch",
     "debug": "nest start --debug --watch",
     "debug:start": "nest start --watch --exec \"node --inspect-brk\"",
-    "build:preview": "node dist/main",
+    "build:preview": "node dist/src/main.js",
     "db:push": "drizzle-kit push",
     "db:generate": "drizzle-kit generate",
     "db:migrate": "drizzle-kit migrate",
     "db:studio": "drizzle-kit studio",
-    "test": "vp test"
+    "test": "vp test",
+    "access:init": "cross-env TS_NODE_PROJECT=tsconfig.scripts.json node -r ts-node/register/transpile-only -r tsconfig-paths/register src/access-init.ts"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "catalog:",
     "@nestjs-modules/ioredis": "catalog:",
+    "@nestjs/bullmq": "catalog:",
     "@nestjs/common": "catalog:",
     "@nestjs/config": "catalog:",
     "@nestjs/core": "catalog:",
     "@nestjs/mapped-types": "catalog:",
     "@nestjs/platform-fastify": "catalog:",
     "argon2": "catalog:",
+    "bullmq": "catalog:",
+    "dayjs": "catalog:",
     "drizzle-orm": "catalog:",
     "drizzle-zod": "catalog:",
-    "fastify": "5.8.5",
+    "fastify": "catalog:",
     "ioredis": "catalog:",
     "nestjs-zod": "catalog:",
     "pg": "catalog:",
@@ -47,6 +52,7 @@
     "@types/express": "catalog:",
     "@types/node": "catalog:",
     "@types/pg": "catalog:",
+    "chokidar": "catalog:",
     "cross-env": "catalog:",
     "dotenv": "catalog:",
     "drizzle-kit": "catalog:",

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

@@ -0,0 +1,45 @@
+import 'reflect-metadata'
+import { ConfigModule } from '@nestjs/config'
+import { Module } from '@nestjs/common'
+import { NestFactory } from '@nestjs/core'
+import { DatabaseModule } from './database/db.module'
+import databaseConfig from './config/database.config'
+import { AccessSeedService } from './modules/access/seed/access-seed.service'
+import { ENV_ARR } from './utils/env-arr'
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({ isGlobal: true, envFilePath: ENV_ARR, load: [databaseConfig] }),
+    DatabaseModule,
+  ],
+  providers: [AccessSeedService],
+})
+class AccessInitializationModule {}
+
+/**
+ * 校验命令行完整账号并执行权限初始化，将结果输出为 JSON，最后关闭 Nest 应用上下文。
+ * @throws 账号缺失、不符合格式或初始化失败时抛出错误，由脚本入口设置失败退出码。
+ */
+async function initialize() {
+  const accountIndex = process.argv.indexOf('--account')
+  const account = accountIndex >= 0 ? process.argv[accountIndex + 1] : undefined
+  if (!account || !/^[A-Za-z0-9_]{4,32}$/.test(account))
+    throw new Error('用法：access:init --account <已注册完整账号>')
+  const app = await NestFactory.createApplicationContext(AccessInitializationModule, {
+    logger: ['error'],
+  })
+  try {
+    const result = await app.get(AccessSeedService).initialize(account)
+    process.stdout.write(`${JSON.stringify(result)}\n`)
+  } finally {
+    await app.close()
+  }
+}
+initialize().then(
+  () => process.exit(0),
+  /** 将初始化失败原因写入标准错误，并使用非零退出码通知脚本调用方。 */
+  (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : '初始化失败'}\n`)
+    process.exit(1)
+  },
+)

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

@@ -6,6 +6,9 @@ import { Public } from './common/decorators/public.decorator'
 export class AppController {
   constructor(private readonly appService: AppService) {}
 
+  /**
+   * 为公开的根路径返回应用欢迎信息，便于快速确认 HTTP 服务可用。
+   */
   @Get()
   @Public()
   getHello(): string {

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

@@ -1,4 +1,12 @@
-import { appConfig, databaseConfig, llmConfig, redisConfig, sessionConfig } from '@/config'
+import {
+  appConfig,
+  databaseConfig,
+  llmConfig,
+  queueConfig,
+  redisConfig,
+  sessionConfig,
+  storageConfig,
+} from '@/config'
 import { RedisModule } from '@nestjs-modules/ioredis'
 import { Module } from '@nestjs/common'
 import { ConfigModule, ConfigService } from '@nestjs/config'
@@ -9,8 +17,15 @@ import { AppService } from './app.service'
 import { GlobalExceptionFilter } from './common/filters/global-exception.filter'
 import { DatabaseModule } from './database/db.module'
 import { AuthModule } from './modules/auth/auth.module'
-import { TestDbModule } from './modules/test/db/db.module'
-import { TestRedisModule } from './modules/test/redis/redis.module'
+import { TaskQueueModule } from './modules/task-queue/task-queue.module'
+import { AccessModule } from './modules/access/access.module'
+import { CompaniesModule } from './modules/companies/companies.module'
+import { ProjectsModule } from './modules/projects/projects.module'
+import { OrganizationModule } from './modules/organization/organization.module'
+import { MembersModule } from './modules/members/members.module'
+import { MenusModule } from './modules/menus/menus.module'
+import { AuditModule } from './modules/audit/audit.module'
+import { UploadModule } from './modules/upload/upload.module'
 import { ENV_ARR } from './utils/env-arr'
 
 @Module({
@@ -18,14 +33,27 @@ import { ENV_ARR } from './utils/env-arr'
     ConfigModule.forRoot({
       isGlobal: true,
       envFilePath: ENV_ARR,
-      load: [appConfig, databaseConfig, llmConfig, redisConfig, sessionConfig],
+      load: [
+        appConfig,
+        databaseConfig,
+        llmConfig,
+        queueConfig,
+        redisConfig,
+        sessionConfig,
+        storageConfig,
+      ],
     }),
     DatabaseModule,
     RedisModule.forRootAsync({
       inject: [ConfigService],
+      /**
+       * 为会话 Redis 创建单节点连接，限制连接和命令等待，并禁用离线排队以便及时暴露故障。
+       */
       useFactory: (config) => ({
         type: 'single',
         options: {
+          // ioredis 6 默认使用 RESP3，显式保留升级前的 RESP2 连接协议。
+          protocol: 2,
           host: config.get('redis.host'),
           port: config.get('redis.port'),
           password: config.get('redis.password'),
@@ -37,9 +65,16 @@ import { ENV_ARR } from './utils/env-arr'
         },
       }),
     }),
-    TestRedisModule,
-    TestDbModule,
+    TaskQueueModule,
     AuthModule,
+    AccessModule,
+    CompaniesModule,
+    OrganizationModule,
+    ProjectsModule,
+    MembersModule,
+    MenusModule,
+    AuditModule,
+    UploadModule,
   ],
   controllers: [AppController],
   providers: [

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

@@ -2,6 +2,9 @@ import { Injectable } from '@nestjs/common'
 
 @Injectable()
 export class AppService {
+  /**
+   * 提供根路径使用的默认欢迎文本。
+   */
   getHello(): string {
     return 'Hello World!'
   }

package/template-vp-monorepo-react-nestjs/apps/server/src/common/adapters/fastify.adapter.ts

@@ -1,6 +1,10 @@
 import { FastifyAdapter } from '@nestjs/platform-fastify'
 import { randomUUID } from 'crypto'
+import { logPasswordSecurityEvent } from '../security/password-security-event'
 
+/**
+ * 创建 Fastify 适配器，配置请求 ID、原始二进制流解析及响应关联 ID。
+ */
 export function createFastifyAdapter() {
   const adapter = new FastifyAdapter({
     trustProxy: true,
@@ -8,9 +12,22 @@ export function createFastifyAdapter() {
     logger: false,
   })
 
+  adapter
+    .getInstance()
+    /** 保留原始二进制请求流，供上传服务逐块处理而无需整段缓冲。 */
+    .addContentTypeParser('application/octet-stream', (_request, payload, done) => {
+      done(null, payload)
+    })
+
+  /** 在所有响应上返回请求关联 ID，便于客户端反馈问题时定位服务端日志。 */
   adapter.getInstance().addHook('onRequest', (request, reply, done) => {
     reply.header('x-request-id', request.id)
     done()
   })
+  /** 以最终 HTTP 状态为准，每条密码操作请求只记录一次固定字段安全事件。 */
+  adapter.getInstance().addHook('onResponse', (request, reply, done) => {
+    logPasswordSecurityEvent(request, reply)
+    done()
+  })
   return adapter
 }

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

@@ -5,14 +5,23 @@ export { isSessionTerminal, SESSION_TERMINALS } from 'shared/utils'
 export const SESSION_KEY_PREFIX = 'auth:v1:session:'
 export const SESSION_SLOT_PREFIX = 'auth:v1:slot:'
 
+/**
+ * 使用令牌摘要构造 Redis 会话键，避免将明文令牌写入键名。
+ */
 export function createSessionKey(tokenDigest: string) {
   return `${SESSION_KEY_PREFIX}${tokenDigest}`
 }
 
+/**
+ * 构造用户与终端对应的唯一会话槽位键，用于同端会话替换。
+ */
 export function createSessionSlotKey(userId: string, terminal: SessionTerminalType) {
   return `${SESSION_SLOT_PREFIX}${userId}:${terminal}`
 }
 
+/**
+ * 根据 User-Agent 优先识别 Electron 桌面端，其次识别移动端，其余归为 Web。
+ */
 export function detectSessionTerminal(userAgent: string | undefined): SessionTerminalType {
   const value = userAgent ?? ''
 

package/template-vp-monorepo-react-nestjs/apps/server/src/common/decorators/access-policy.decorator.ts

@@ -0,0 +1,18 @@
+import { SetMetadata } from '@nestjs/common'
+import type { ScopeType } from 'shared/types'
+
+export const ACCESS_POLICY_KEY = 'access-policy'
+export interface AccessPolicyDefinition {
+  scope: ScopeType | 'authenticated' | 'route'
+  permission?: string | string[]
+  adminOnly?: boolean
+}
+/**
+ * 将作用域、权限及管理员限制写入 Nest 元数据，供权限守卫读取。
+ */
+export const AccessPolicy = (policy: AccessPolicyDefinition) =>
+  SetMetadata(ACCESS_POLICY_KEY, policy)
+/**
+ * 标记路由只要求登录身份，由权限守卫跳过具体业务权限校验。
+ */
+export const Authenticated = () => AccessPolicy({ scope: 'authenticated' })

package/template-vp-monorepo-react-nestjs/apps/server/src/common/decorators/current-auth.decorator.ts

@@ -4,6 +4,10 @@ import { createParamDecorator, ExecutionContext } from '@nestjs/common'
 import { AppException } from '../exceptions/app.exception'
 
 export const CurrentAuth = createParamDecorator(
+  /**
+   * 从守卫写入的请求上下文提取当前身份，作为控制器方法参数。
+   * @throws 上下文缺少身份时抛出认证上下文缺失错误。
+   */
   (_data: unknown, context: ExecutionContext): CurrentAuthType => {
     const request = context.switchToHttp().getRequest<AuthenticatedRequest>()
 

package/template-vp-monorepo-react-nestjs/apps/server/src/common/decorators/public.decorator.ts

@@ -1,4 +1,7 @@
 import { SetMetadata } from '@nestjs/common'
 import { IS_PUBLIC_KEY } from '../constants/auth'
 
+/**
+ * 标记路由或控制器为公开入口，供认证守卫放行。
+ */
 export const Public = () => SetMetadata(IS_PUBLIC_KEY, true)

package/template-vp-monorepo-react-nestjs/apps/server/src/common/exceptions/app.exception.ts

@@ -15,6 +15,10 @@ export interface AppExceptionOptions {
   readonly details?: readonly ApiErrorDetail[]
 }
 
+/**
+ * 校验业务错误码、公开文案和 HTTP 状态，并要求 401 错误声明 Bearer 质询。
+ * @throws 错误定义不满足约定时抛出 TypeError。
+ */
 function assertErrorDefinition(definition: AppErrorDefinition): void {
   if (!ERROR_CODE_PATTERN.test(definition.code) || definition.code.length > 80) {
     throw new TypeError('Invalid application error code: ' + definition.code)
@@ -41,6 +45,11 @@ export class AppException extends HttpException {
   readonly definition: AppErrorDefinition
   readonly details?: readonly ApiErrorDetail[]
 
+  /**
+   * 创建携带稳定业务错误定义的 HTTP 异常。
+   * @param options 保留内部原因用于日志，附加可公开的字段错误详情。
+   * @throws 错误定义不合法时抛出 TypeError。
+   */
   constructor(definition: AppErrorDefinition, options: AppExceptionOptions = {}) {
     assertErrorDefinition(definition)
 

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

@@ -13,6 +13,7 @@ import { ApiErrorDetail, ApiFailure } from 'shared/types'
 import { ZodError } from 'zod'
 import { COMMON_ERRORS } from '../error/common.error'
 import { AppException } from '../exceptions/app.exception'
+import { markPasswordFailure } from '../security/password-security-event'
 
 interface PublicHttpError {
   readonly code: string
@@ -80,6 +81,9 @@ const PUBLIC_HTTP_ERRORS: Readonly<Record<number, PublicHttpError>> = {
   },
 }
 
+/**
+ * 将公开文本中的控制字符替换为空格并限制长度；非字符串返回空串。
+ */
 function cleanPublicText(value: unknown, maxLength: number): string {
   if (typeof value !== 'string') {
     return ''
@@ -99,6 +103,9 @@ function cleanPublicText(value: unknown, maxLength: number): string {
   )
 }
 
+/**
+ * 清理字段错误码并校验允许字符，非法值统一替换为 invalid。
+ */
 function cleanDetailCode(value: unknown): string {
   const code = cleanPublicText(value, MAX_DETAIL_CODE_LENGTH)
   if (/^[A-Za-z][A-Za-z0-9._-]*$/.test(code)) {
@@ -107,9 +114,13 @@ function cleanDetailCode(value: unknown): string {
   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) || '请求内容无效'
@@ -123,6 +134,9 @@ function normalizeDetails(
   return normalized?.length ? normalized : undefined
 }
 
+/**
+ * 仅接受 400 至 599 的整数 HTTP 状态，其他值回退为 500。
+ */
 function normalizeStatus(value: unknown): number {
   if (typeof value !== 'number' || !Number.isInteger(value)) {
     return HttpStatus.INTERNAL_SERVER_ERROR
@@ -162,10 +176,8 @@ function sanitizeLogText(value: string, maxLength: number): string {
     .slice(0, maxLength)
 }
 /**
- * /u2028 行分隔符
- * /u2029 段落分隔符
- * @param error
- * @returns
+ * 提取数量和长度受限的脱敏堆栈帧，消息中包含换行时不采信堆栈内容。
+ * @returns 可用于结构化日志的调用帧；堆栈缺失或不可信时返回 undefined。
  */
 function sanitizeStackFrame(error: Error): string[] | undefined {
   if (!error.stack || /[\r\n\u2028\u2029]/.test(error.message)) {
@@ -183,6 +195,9 @@ function sanitizeStackFrame(error: Error): string[] | undefined {
   return frames.length ? frames : undefined
 }
 
+/**
+ * 生成脱敏后的日志错误对象，最多递归保留两层 cause，避免泄漏凭据或无限遍历。
+ */
 function serializeError(value: unknown, depth = 0): Record<string, unknown> {
   if (!(value instanceof Error)) {
     return {
@@ -208,6 +223,9 @@ export class GlobalExceptionFilter implements ExceptionFilter {
 
   constructor(private readonly adapterHost: HttpAdapterHost) {}
 
+  /**
+   * 从请求参数校验异常提取数量和长度受限的公开字段错误。
+   */
   private getZodDetails(exception: ZodValidationException): ApiErrorDetail[] | undefined {
     const zodError = exception.getZodError()
 
@@ -215,6 +233,7 @@ export class GlobalExceptionFilter implements ExceptionFilter {
       return undefined
     }
 
+    /** 将 Zod 路径转换成点分隔字段路径，并过滤不适合公开的控制字符。 */
     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) || '请求内容无效'
@@ -228,6 +247,9 @@ export class GlobalExceptionFilter implements ExceptionFilter {
     return details.length ? details : undefined
   }
 
+  /**
+   * 将 Nest HTTP 异常映射为固定公开文案，隐藏内部异常文本并标记 401 质询。
+   */
   private normalizeLegacyHttpException(exception: HttpException): NormalizedFailure {
     const status = normalizeStatus(exception.getStatus())
 
@@ -263,6 +285,9 @@ export class GlobalExceptionFilter implements ExceptionFilter {
     }
   }
 
+  /**
+   * 统一转换业务异常、Zod 异常和未知异常，生成安全响应及仅供服务端日志使用的原因。
+   */
   private normalize(exception: unknown): NormalizedFailure {
     if (exception instanceof ZodSerializationException) {
       return {
@@ -320,6 +345,9 @@ export class GlobalExceptionFilter implements ExceptionFilter {
     }
   }
 
+  /**
+   * 记录带请求关联 ID 的 5xx 日志，使用路由模板并对异常原因脱敏。
+   */
   private logServerFailure(
     exception: unknown,
     normalized: NormalizedFailure,
@@ -340,6 +368,10 @@ export class GlobalExceptionFilter implements ExceptionFilter {
     })
   }
 
+  /**
+   * 捕获 HTTP 异常，记录服务端故障并返回统一错误结构、请求 ID 和必要的 Bearer 质询。
+   * @remarks 响应头已发送时只结束响应，避免重复写入。
+   */
   catch(exception: unknown, host: ArgumentsHost): void {
     const http = host.switchToHttp()
     const request = http.getRequest<FastifyRequest>()
@@ -347,9 +379,10 @@ export class GlobalExceptionFilter implements ExceptionFilter {
     const requestId = String(request.id)
     const normalized = this.normalize(exception)
     const { httpAdapter } = this.adapterHost
+    const passwordRequest = markPasswordFailure(request, normalized.body.code)
 
     // 只记录服务器错误 业务错误不记录
-    if (normalized.status >= 500) {
+    if (normalized.status >= 500 && !passwordRequest) {
       this.logServerFailure(exception, normalized, request, requestId)
     }
 

package/template-vp-monorepo-react-nestjs/apps/server/src/common/security/password-security-event.ts

@@ -0,0 +1,98 @@
+import { Logger } from '@nestjs/common'
+import { z } from 'zod'
+
+/** 仅依赖安全事件所需的请求字段，兼容 Nest 适配器与应用侧 Fastify 类型。 */
+interface PasswordEventRequest {
+  method: string
+  routeOptions?: { url?: string }
+  id: string
+  auth?: { userId: string }
+}
+
+const logger = new Logger('PasswordSecurityEvent')
+const failureCodes = new WeakMap<PasswordEventRequest, string>()
+const resolvedTargets = new WeakMap<PasswordEventRequest, string>()
+const uuidSchema = z.uuid()
+
+type PasswordEvent = 'account.password.change' | 'account.password.reset'
+
+/** 仅按框架匹配的路由模板识别改密接口，不读取含用户输入的原始 URL。 */
+function passwordEventForRoute(request: PasswordEventRequest): PasswordEvent | null {
+  if (request.method !== 'POST') return null
+  switch (request.routeOptions?.url) {
+    case '/auth/change-password':
+      return 'account.password.change'
+    case '/platform/accounts/:userId/reset-password':
+      return 'account.password.reset'
+    default:
+      return null
+  }
+}
+
+/** 记录统一异常过滤器选定的公开错误码，供响应结束时安全记录使用。 */
+export function markPasswordFailure(request: PasswordEventRequest, reasonCode: string): boolean {
+  if (!passwordEventForRoute(request)) return false
+  failureCodes.set(request, reasonCode)
+  return true
+}
+
+/** 只在业务层确认目标账号存在后写入其 ID；守卫拒绝及目标缺失均保持 null。 */
+export function markPasswordTargetResolved(
+  request: PasswordEventRequest,
+  targetUserId: string,
+): void {
+  if (
+    passwordEventForRoute(request) === 'account.password.reset' &&
+    uuidSchema.safeParse(targetUserId).success
+  ) {
+    resolvedTargets.set(request, targetUserId)
+  }
+}
+
+/** 将未进入统一异常过滤器的 HTTP 失败映射为稳定且不含请求内容的原因码。 */
+function fallbackReasonCode(status: number): string {
+  switch (status) {
+    case 400:
+      return 'COMMON.BAD_REQUEST'
+    case 401:
+      return 'COMMON.UNAUTHORIZED'
+    case 403:
+      return 'COMMON.FORBIDDEN'
+    case 404:
+      return 'COMMON.NOT_FOUND'
+    case 503:
+      return 'AUTH.SERVICE_UNAVAILABLE'
+    default:
+      return status >= 500 ? 'COMMON.INTERNAL_SERVER_ERROR' : `COMMON.HTTP_${status}`
+  }
+}
+
+/**
+ * 每个改密请求在响应结束后只输出一条固定字段事件，覆盖守卫、参数校验和业务失败。
+ * 事件不遍历请求体、响应体或异常对象，避免凭据与摘要进入日志。
+ */
+export function logPasswordSecurityEvent(
+  request: PasswordEventRequest,
+  reply: { statusCode: number },
+): void {
+  const event = passwordEventForRoute(request)
+  if (!event) return
+
+  const actorUserId = request.auth?.userId ?? null
+  const targetUserId =
+    event === 'account.password.change' ? actorUserId : (resolvedTargets.get(request) ?? null)
+  const success = reply.statusCode >= 200 && reply.statusCode < 300
+  const reasonCode = success
+    ? null
+    : (failureCodes.get(request) ?? fallbackReasonCode(reply.statusCode))
+
+  logger.log({
+    event,
+    actorUserId,
+    targetUserId,
+    requestId: String(request.id),
+    result: success ? 'success' : 'failure',
+    reasonCode,
+    occurredAt: new Date().toISOString(),
+  })
+}

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

@@ -1,5 +1,8 @@
 import { registerAs } from '@nestjs/config'
 
+/**
+ * 加载 HTTP 端口和运行环境，未配置时使用开发环境默认值。
+ */
 export default registerAs('app', () => ({
   port: Number.parseInt(process.env.PORT ?? '3000', 10),
   env: process.env.NODE_ENV ?? 'development',

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

@@ -1,5 +1,8 @@
 import { registerAs } from '@nestjs/config'
 
+/**
+ * 加载 PostgreSQL 连接配置，供连接池和数据库工具使用。
+ */
 export default registerAs('database', () => ({
   url: process.env.DATABASE_URL,
   host: process.env.DB_HOST ?? 'localhost',

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

@@ -1,5 +1,7 @@
 export { default as appConfig } from './app.config'
 export { default as databaseConfig } from './database.config'
 export { default as llmConfig } from './llm.config'
+export { default as queueConfig } from './queue.config'
 export { default as redisConfig } from './redis.config'
 export { default as sessionConfig } from './session.config'
+export { default as storageConfig } from './storage.config'

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

@@ -1,5 +1,8 @@
 import { registerAs } from '@nestjs/config'
 
+/**
+ * 加载大模型服务地址、模型名和访问密钥。
+ */
 export default registerAs('llm', () => ({
   url: process.env.LLM_API_URL,
   model: process.env.LLM_API_MODEL,