create-bubbles 0.1.25 → 0.1.27

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

@@ -0,0 +1,119 @@
+import { registerAs } from '@nestjs/config'
+
+export interface QueueConfig {
+  /** 队列专用 Redis 地址。来自 QUEUE_REDIS_HOST，缺省 localhost。独立于 Session Redis，不与其共用连接配置。 */
+  host: string
+  /** 队列专用 Redis 端口。来自 QUEUE_REDIS_PORT，缺省 6379，取值范围 1~65535。 */
+  port: number
+  /** Redis ACL 用户名（Redis 6+），来自 QUEUE_REDIS_USERNAME。可选，无认证开发环境可留空。 */
+  username?: string
+  /** Redis 密码，来自 QUEUE_REDIS_PASSWORD。可选；生产值应放部署 Secret，不提交进 Git。 */
+  password?: string
+  /**
+   * Redis 逻辑库编号。来自 QUEUE_REDIS_DB。
+   * 约定：开发环境 Session 用 DB 0、队列用 DB 1，便于隔离查看；生产建议独立 Redis 且用 DB 0；Redis Cluster 只支持 DB 0。
+   */
+  db: number
+  /**
+   * 所有队列 key 的统一前缀。来自 QUEUE_PREFIX，缺省 `bubbles:{NODE_ENV}:queue`。
+   * 用于区分项目和环境、避免不同环境撞键。注意：这是 BullMQ 自身的 prefix，不要配置 ioredis 的 keyPrefix。
+   */
+  prefix: string
+  /**
+   * 当前 NestJS 进程是否启动 BullMQ Worker（消费者）。来自 QUEUE_WORKER_ENABLED，严格解析 true/false。
+   * 设为 false 时仍可投递任务，但本进程不消费，为以后拆分独立 Worker 进程留出入口。
+   */
+  workerEnabled: boolean
+  /** 单个任务的总执行次数上限。来自 QUEUE_DEFAULT_ATTEMPTS，缺省 3。注意是“总共最多 3 次”，不是首次外加 3 次重试。 */
+  defaultAttempts: number
+  /** 重试退避的基础延迟（毫秒），配合指数退避使用。来自 QUEUE_BACKOFF_DELAY_MS，缺省 1000，即 1s、2s、4s…。 */
+  backoffDelayMs: number
+  /** 已完成任务（removeOnComplete.age）的保留时长（秒），超时自动清理。来自 QUEUE_COMPLETED_AGE_SECONDS，缺省 86400（24 小时）。 */
+  completedAgeSeconds: number
+  /** 已完成任务（removeOnComplete.count）的最大保留条数。来自 QUEUE_COMPLETED_COUNT，缺省 1000。与保留时长同时生效，防止 Redis 无限增长。 */
+  completedCount: number
+  /** 失败任务（removeOnFail.age）的保留时长（秒）。来自 QUEUE_FAILED_AGE_SECONDS，缺省 604800（7 天），比成功任务留得更久，便于排查。 */
+  failedAgeSeconds: number
+  /** 失败任务（removeOnFail.count）的最大保留条数。来自 QUEUE_FAILED_COUNT，缺省 5000。 */
+  failedCount: number
+}
+
+/**
+ * 读取环境变量并校验为指定闭区间内的安全整数，缺省时使用回退值。
+ * @throws 空值、非整数或越界时抛出配置错误。
+ */
+function readInteger(
+  name: string,
+  fallback: number,
+  minimum: number,
+  maximum = Number.MAX_SAFE_INTEGER,
+) {
+  const rawValue = (process.env[name] ?? String(fallback)).trim()
+  const value = Number(rawValue)
+
+  if (rawValue === '' || !Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new Error(name + ' must be an integer between ' + minimum + ' and ' + maximum)
+  }
+
+  return value
+}
+
+/**
+ * 将环境变量严格解析为 true 或 false，未设置时使用默认值。
+ * @throws 已设置但不是布尔文本时抛出配置错误。
+ */
+function readBoolean(name: string, fallback: boolean) {
+  const rawValue = process.env[name]
+
+  if (rawValue === undefined) {
+    return fallback
+  }
+
+  const value = rawValue.trim().toLowerCase()
+
+  if (value === 'true') {
+    return true
+  }
+
+  if (value === 'false') {
+    return false
+  }
+
+  throw new Error(name + ' must be true or false')
+}
+
+/**
+ * 读取可选环境变量并去除首尾空格，空白值统一视为未配置。
+ */
+function readOptionalText(name: string) {
+  const value = process.env[name]?.trim()
+  return value ? value : undefined
+}
+
+/**
+ * 构建并校验队列专属 Redis、消费者开关、重试和任务保留策略。
+ */
+export default registerAs('queue', (): QueueConfig => {
+  const environment = process.env.NODE_ENV ?? 'development'
+  const prefix = process.env.QUEUE_PREFIX?.trim() || ['bubbles', environment, 'queue'].join(':')
+
+  if (!prefix) {
+    throw new Error('QUEUE_PREFIX must not be empty')
+  }
+
+  return {
+    host: process.env.QUEUE_REDIS_HOST?.trim() || 'localhost',
+    port: readInteger('QUEUE_REDIS_PORT', 6379, 1, 65_535),
+    username: readOptionalText('QUEUE_REDIS_USERNAME'),
+    password: readOptionalText('QUEUE_REDIS_PASSWORD'),
+    db: readInteger('QUEUE_REDIS_DB', 1, 0),
+    prefix,
+    workerEnabled: readBoolean('QUEUE_WORKER_ENABLED', true),
+    defaultAttempts: readInteger('QUEUE_DEFAULT_ATTEMPTS', 3, 1),
+    backoffDelayMs: readInteger('QUEUE_BACKOFF_DELAY_MS', 1_000, 1),
+    completedAgeSeconds: readInteger('QUEUE_COMPLETED_AGE_SECONDS', 86_400, 1),
+    completedCount: readInteger('QUEUE_COMPLETED_COUNT', 1_000, 1),
+    failedAgeSeconds: readInteger('QUEUE_FAILED_AGE_SECONDS', 604_800, 1),
+    failedCount: readInteger('QUEUE_FAILED_COUNT', 5_000, 1),
+  }
+})

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

@@ -7,6 +7,9 @@ export interface RedisConfig {
   db: number
 }
 
+/**
+ * 加载会话 Redis 的单节点连接配置及逻辑库编号。
+ */
 export default registerAs(
   'redis',
   (): RedisConfig => ({

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

@@ -1,5 +1,9 @@
 import { registerAs } from '@nestjs/config'
 
+/**
+ * 按十进制读取会话时长配置，并确保解析结果为正安全整数。
+ * @throws 解析失败或非正数时抛出配置错误。
+ */
 function readPositiveInteger(name: string, fallback: number) {
   const value = Number.parseInt(process.env[name] ?? String(fallback), 10)
 
@@ -9,6 +13,9 @@ function readPositiveInteger(name: string, fallback: number) {
   return value
 }
 
+/**
+ * 校验令牌摘要密钥和闲置、绝对有效期，并将会话时长转换为毫秒。
+ */
 export default registerAs('session', () => {
   const tokenPepper = process.env.SESSION_TOKEN_PEPPER
   /**

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

@@ -0,0 +1,42 @@
+import { registerAs } from '@nestjs/config'
+
+const SESSION_TTL_MS = 24 * 60 * 60 * 1000
+/**
+ * 读取并修剪必填环境变量，缺失或只有空白时终止配置加载。
+ */
+function readRequired(name: string): string {
+  const value = process.env[name]?.trim()
+
+  if (!value) {
+    throw new Error(`${name} is required`)
+  }
+
+  return value
+}
+
+/**
+ * 验证存储端点为 HTTP 或 HTTPS URL，并去掉末尾斜杠供 S3 客户端使用。
+ */
+function readEndpoint(): string {
+  const value = readRequired('STORAGE_ENDPOINT')
+  const url = new URL(value)
+
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('STORAGE_ENDPOINT must use http or https')
+  }
+
+  return url.toString().replace(/\/$/, '')
+}
+
+/**
+ * 加载并校验对象存储连接凭据、目标桶和上传会话有效期。
+ */
+export default registerAs('storage', () => ({
+  endpoint: readEndpoint(),
+  region: process.env.STORAGE_REGION?.trim() || 'us-east-1',
+  accessKeyId: readRequired('STORAGE_ACCESS_KEY_ID'),
+  secretAccessKey: readRequired('STORAGE_SECRET_ACCESS_KEY'),
+  bucket: readRequired('STORAGE_BUCKET'),
+  forcePathStyle: true,
+  sessionTtlMs: SESSION_TTL_MS,
+}))

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

@@ -0,0 +1,394 @@
+import { sql } from 'drizzle-orm'
+import {
+  boolean,
+  check,
+  foreignKey,
+  index,
+  integer,
+  jsonb,
+  pgEnum,
+  pgTable,
+  primaryKey,
+  text,
+  timestamp,
+  unique,
+  uniqueIndex,
+  uuid,
+  varchar,
+} from 'drizzle-orm/pg-core'
+import { users } from './schema'
+
+export const accessStatus = pgEnum('access_status', ['active', 'disabled'])
+export const scopeType = pgEnum('access_scope_type', ['platform', 'company', 'project'])
+export const menuType = pgEnum('menu_type', ['directory', 'page', 'operation'])
+export const builtinRole = pgEnum('builtin_role', ['administrator', 'member'])
+export const companyEntityType = pgEnum('company_entity_type', ['group', 'company'])
+export const companyMemberInvitationStatus = pgEnum('company_member_invitation_status', [
+  'pending',
+  'accepted',
+  'revoked',
+])
+/**
+ * 为每张权限业务表创建独立的创建时间与更新时间列定义，并由数据库提供默认当前时间。
+ */
+const times = () => ({
+  createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
+})
+
+export const companies = pgTable(
+  'companies',
+  {
+    id: uuid('id').defaultRandom().primaryKey(),
+    parentCompanyId: uuid('parent_company_id'),
+    entityType: companyEntityType('entity_type').notNull().default('company'),
+    name: varchar('name', { length: 100 }).notNull(),
+    nameKey: text('name_key').notNull(),
+    code: varchar('code', { length: 64 }).notNull(),
+    description: text('description').notNull().default(''),
+    sort: integer('sort').notNull().default(1),
+    status: accessStatus('status').notNull().default('active'),
+    version: integer('version').notNull().default(1),
+    ...times(),
+  },
+  /**
+   * 约束企业层级、规范化名称、编码唯一性、排序及版本号。
+   */
+  (t) => [
+    foreignKey({ columns: [t.parentCompanyId], foreignColumns: [t.id] }).onDelete('restrict'),
+    uniqueIndex('companies_root_name_key_uq')
+      .on(t.nameKey)
+      .where(sql`${t.parentCompanyId} IS NULL`),
+    uniqueIndex('companies_parent_name_key_uq')
+      .on(t.parentCompanyId, t.nameKey)
+      .where(sql`${t.parentCompanyId} IS NOT NULL`),
+    uniqueIndex('companies_code_normalized_uq').on(sql`lower(normalize(btrim(${t.code}), NFKC))`),
+    check(
+      'companies_name_key_normalized',
+      sql`${t.nameKey} = lower(normalize(btrim(${t.name}), NFKC))`,
+    ),
+    check('companies_sort_range', sql`${t.sort} BETWEEN 0 AND 999999999`),
+    check('companies_version_positive', sql`${t.version} > 0`),
+  ],
+)
+export const projects = pgTable(
+  'projects',
+  {
+    id: uuid('id').defaultRandom().primaryKey(),
+    companyId: uuid('company_id')
+      .notNull()
+      .references(() => companies.id),
+    name: varchar('name', { length: 100 }).notNull(),
+    code: varchar('code', { length: 64 }).notNull(),
+    description: text('description').notNull().default(''),
+    status: accessStatus('status').notNull().default('active'),
+    version: integer('version').notNull().default(1),
+    ...times(),
+  },
+  /**
+   * 约束公司内项目编码唯一及版本有效，并为公司下的项目状态查询建立索引。
+   */
+  (t) => [
+    uniqueIndex('projects_company_code_normalized_uq').on(
+      t.companyId,
+      sql`lower(normalize(btrim(${t.code}), NFKC))`,
+    ),
+    unique('projects_company_id_uq').on(t.companyId, t.id),
+    check('projects_version_positive', sql`${t.version} > 0`),
+    index('projects_company_status_idx').on(t.companyId, t.status),
+  ],
+)
+export const companyMembers = pgTable(
+  'company_members',
+  {
+    id: uuid('id').defaultRandom().primaryKey(),
+    companyId: uuid('company_id')
+      .notNull()
+      .references(() => companies.id),
+    userId: uuid('user_id')
+      .notNull()
+      .references(() => users.id),
+    status: accessStatus('status').notNull().default('active'),
+    version: integer('version').notNull().default(1),
+    ...times(),
+  },
+  /**
+   * 约束公司成员关系唯一及版本有效，并为按用户查找成员关系建立索引。
+   */
+  (t) => [
+    unique('company_members_company_user_uq').on(t.companyId, t.userId),
+    check('company_members_version_positive', sql`${t.version} > 0`),
+    index('company_members_user_idx').on(t.userId),
+  ],
+)
+export const companyMemberInvitations = pgTable(
+  'company_member_invitations',
+  {
+    id: uuid('id').defaultRandom().primaryKey(),
+    companyId: uuid('company_id')
+      .notNull()
+      .references(() => companies.id, { onDelete: 'restrict' }),
+    tokenDigest: varchar('token_digest', { length: 64 }).notNull(),
+    status: companyMemberInvitationStatus('status').notNull().default('pending'),
+    createdByUserId: uuid('created_by_user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'restrict' }),
+    acceptedByUserId: uuid('accepted_by_user_id').references(() => users.id, {
+      onDelete: 'restrict',
+    }),
+    expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(),
+    acceptedAt: timestamp('accepted_at', { withTimezone: true }),
+    revokedAt: timestamp('revoked_at', { withTimezone: true }),
+    version: integer('version').notNull().default(1),
+    ...times(),
+  },
+  /**
+   * 保证邀请 token 摘要全局唯一、状态时间字段一致，并优化企业邀请列表和过期判断。
+   */
+  (t) => [
+    uniqueIndex('company_member_invitations_token_digest_uq').on(t.tokenDigest),
+    index('company_member_invitations_company_status_created_idx').on(
+      t.companyId,
+      t.status,
+      t.createdAt,
+      t.id,
+    ),
+    index('company_member_invitations_pending_expires_idx')
+      .on(t.expiresAt)
+      .where(sql`${t.status} = 'pending'`),
+    check(
+      'company_member_invitations_token_digest_length',
+      sql`char_length(${t.tokenDigest}) = 64`,
+    ),
+    check('company_member_invitations_version_positive', sql`${t.version} > 0`),
+    check(
+      'company_member_invitations_state_check',
+      sql`(${t.status} = 'pending' AND ${t.acceptedByUserId} IS NULL AND ${t.acceptedAt} IS NULL AND ${t.revokedAt} IS NULL) OR (${t.status} = 'accepted' AND ${t.acceptedByUserId} IS NOT NULL AND ${t.acceptedAt} IS NOT NULL AND ${t.revokedAt} IS NULL) OR (${t.status} = 'revoked' AND ${t.acceptedByUserId} IS NULL AND ${t.acceptedAt} IS NULL AND ${t.revokedAt} IS NOT NULL)`,
+    ),
+  ],
+)
+export const projectMembers = pgTable(
+  'project_members',
+  {
+    id: uuid('id').defaultRandom().primaryKey(),
+    companyId: uuid('company_id').notNull(),
+    projectId: uuid('project_id').notNull(),
+    userId: uuid('user_id').notNull(),
+    status: accessStatus('status').notNull().default('active'),
+    version: integer('version').notNull().default(1),
+    ...times(),
+  },
+  /**
+   * 通过组合外键确保项目与成员归属同一公司，并约束项目成员唯一及版本有效。
+   */
+  (t) => [
+    unique('project_members_project_user_uq').on(t.projectId, t.userId),
+    foreignKey({
+      columns: [t.companyId, t.projectId],
+      foreignColumns: [projects.companyId, projects.id],
+    }),
+    foreignKey({
+      columns: [t.companyId, t.userId],
+      foreignColumns: [companyMembers.companyId, companyMembers.userId],
+    }),
+    check('project_members_version_positive', sql`${t.version} > 0`),
+    index('project_members_user_idx').on(t.userId),
+  ],
+)
+export const roles = pgTable(
+  'roles',
+  {
+    id: uuid('id').defaultRandom().primaryKey(),
+    scopeType: scopeType('scope_type').notNull(),
+    companyId: uuid('company_id').references(() => companies.id),
+    projectId: uuid('project_id').references(() => projects.id),
+    name: varchar('name', { length: 100 }).notNull(),
+    description: text('description').notNull().default(''),
+    builtin: builtinRole('builtin'),
+    version: integer('version').notNull().default(1),
+    ...times(),
+  },
+  /**
+   * 约束角色作用域与所属资源一致，并按作用域保证角色名称及内置角色唯一。
+   */
+  (t) => [
+    check(
+      'roles_scope_check',
+      sql`(${t.scopeType} = 'platform' AND ${t.companyId} IS NULL AND ${t.projectId} IS NULL) OR (${t.scopeType} = 'company' AND ${t.companyId} IS NOT NULL AND ${t.projectId} IS NULL) OR (${t.scopeType} = 'project' AND ${t.companyId} IS NOT NULL AND ${t.projectId} IS NOT NULL)`,
+    ),
+    foreignKey({
+      columns: [t.companyId, t.projectId],
+      foreignColumns: [projects.companyId, projects.id],
+    }),
+    uniqueIndex('roles_platform_name_uq')
+      .on(t.name)
+      .where(sql`${t.scopeType} = 'platform'`),
+    uniqueIndex('roles_company_name_uq')
+      .on(t.companyId, t.name)
+      .where(sql`${t.scopeType} = 'company'`),
+    uniqueIndex('roles_project_name_uq')
+      .on(t.projectId, t.name)
+      .where(sql`${t.scopeType} = 'project'`),
+    uniqueIndex('roles_platform_builtin_uq')
+      .on(t.builtin)
+      .where(sql`${t.scopeType} = 'platform' AND ${t.builtin} IS NOT NULL`),
+    uniqueIndex('roles_company_builtin_uq')
+      .on(t.companyId, t.builtin)
+      .where(sql`${t.scopeType} = 'company' AND ${t.builtin} IS NOT NULL`),
+    uniqueIndex('roles_project_builtin_uq')
+      .on(t.projectId, t.builtin)
+      .where(sql`${t.scopeType} = 'project' AND ${t.builtin} IS NOT NULL`),
+    check('roles_version_positive', sql`${t.version} > 0`),
+  ],
+)
+export const userRoles = pgTable(
+  'user_roles',
+  {
+    userId: uuid('user_id')
+      .notNull()
+      .references(() => users.id),
+    roleId: uuid('role_id')
+      .notNull()
+      .references(() => roles.id, { onDelete: 'cascade' }),
+  },
+  /**
+   * 以用户和角色组成联合主键，避免重复授权，并为角色成员查询建立索引。
+   */
+  (t) => [primaryKey({ columns: [t.userId, t.roleId] }), index('user_roles_role_idx').on(t.roleId)],
+)
+export const permissions = pgTable(
+  'permissions',
+  {
+    key: varchar('key', { length: 150 }).primaryKey(),
+    scopeType: scopeType('scope_type').notNull(),
+    title: varchar('title', { length: 100 }).notNull(),
+    routeKey: varchar('route_key', { length: 120 }).notNull(),
+    kind: varchar('kind', { length: 20 }).notNull(),
+    pagePermissionKey: varchar('page_permission_key', { length: 150 }),
+    adminOnly: boolean('admin_only').notNull().default(false),
+    deprecated: boolean('deprecated').notNull().default(false),
+  },
+  /**
+   * 约束操作权限必须引用同作用域的页面权限，页面权限不能再引用父页面。
+   */
+  (t) => [
+    unique('permissions_scope_key_uq').on(t.scopeType, t.key),
+    foreignKey({
+      columns: [t.scopeType, t.pagePermissionKey],
+      foreignColumns: [t.scopeType, t.key],
+    }),
+    check(
+      'permissions_kind_check',
+      sql`(${t.kind} = 'page' AND ${t.pagePermissionKey} IS NULL) OR (${t.kind} = 'operation' AND ${t.pagePermissionKey} IS NOT NULL AND ${t.pagePermissionKey} <> ${t.key})`,
+    ),
+  ],
+)
+export const rolePermissions = pgTable(
+  'role_permissions',
+  {
+    roleId: uuid('role_id')
+      .notNull()
+      .references(() => roles.id, { onDelete: 'cascade' }),
+    permissionKey: varchar('permission_key', { length: 150 })
+      .notNull()
+      .references(() => permissions.key),
+  },
+  /**
+   * 以角色和权限组成联合主键，避免重复授权，并为权限反查角色建立索引。
+   */
+  (t) => [
+    primaryKey({ columns: [t.roleId, t.permissionKey] }),
+    index('role_permissions_key_idx').on(t.permissionKey),
+  ],
+)
+export const menus = pgTable(
+  'menus',
+  {
+    id: uuid('id').defaultRandom().primaryKey(),
+    scopeType: scopeType('scope_type').notNull(),
+    parentId: uuid('parent_id'),
+    type: menuType('type').notNull(),
+    name: varchar('name', { length: 100 }).notNull(),
+    icon: varchar('icon', { length: 80 }).notNull().default(''),
+    sort: integer('sort').notNull().default(0),
+    hidden: boolean('hidden').notNull().default(false),
+    status: accessStatus('status').notNull().default('active'),
+    routeKey: varchar('route_key', { length: 120 }),
+    permissionKey: varchar('permission_key', { length: 150 }).references(() => permissions.key),
+    protected: boolean('protected').notNull().default(false),
+    ...times(),
+  },
+  /**
+   * 约束菜单父子关系及作用域内页面、权限唯一，并优化菜单树查询。
+   */
+  (t) => [
+    foreignKey({ columns: [t.parentId], foreignColumns: [t.id] }),
+    unique('menus_permission_uq').on(t.scopeType, t.permissionKey),
+    uniqueIndex('menus_page_uq')
+      .on(t.scopeType, t.routeKey)
+      .where(sql`${t.type} = 'page'`),
+    index('menus_scope_parent_idx').on(t.scopeType, t.parentId),
+  ],
+)
+export const auditLogs = pgTable(
+  'audit_logs',
+  {
+    id: uuid('id').defaultRandom().primaryKey(),
+    actorUserId: uuid('actor_user_id')
+      .notNull()
+      .references(() => users.id),
+    actorAccount: varchar('actor_account', { length: 32 }).notNull(),
+    actorName: varchar('actor_name', { length: 100 }).notNull(),
+    scopeType: scopeType('scope_type').notNull(),
+    companyId: uuid('company_id'),
+    projectId: uuid('project_id'),
+    action: varchar('action', { length: 120 }).notNull(),
+    objectType: varchar('object_type', { length: 60 }).notNull(),
+    objectId: text('object_id').notNull(),
+    summary: jsonb('summary')
+      .$type<Record<string, string | number | boolean | null | string[]>>()
+      .notNull(),
+    requestId: varchar('request_id', { length: 128 }).notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+  },
+  /**
+   * 约束审计范围与公司、项目归属一致，并优化范围内按时间和 ID 查询日志。
+   */
+  (t) => [
+    check(
+      'audit_scope_check',
+      sql`(${t.scopeType} = 'platform' AND ${t.companyId} IS NULL AND ${t.projectId} IS NULL) OR (${t.scopeType} = 'company' AND ${t.companyId} IS NOT NULL AND ${t.projectId} IS NULL) OR (${t.scopeType} = 'project' AND ${t.companyId} IS NOT NULL AND ${t.projectId} IS NOT NULL)`,
+    ),
+    index('audit_scope_created_idx').on(t.scopeType, t.companyId, t.projectId, t.createdAt, t.id),
+  ],
+)
+export const menuVersions = pgTable(
+  'menu_versions',
+  {
+    scopeType: scopeType('scope_type').primaryKey(),
+    version: integer('version').notNull().default(1),
+  },
+  /**
+   * 确保每个作用域的菜单版本号始终为正数。
+   */
+  (t) => [check('menu_versions_positive', sql`${t.version} > 0`)],
+)
+export const cleanupTombstones = pgTable('permission_cleanup_tombstones', {
+  permissionKey: varchar('permission_key', { length: 150 }).primaryKey(),
+  cleanedAt: timestamp('cleaned_at', { withTimezone: true }).defaultNow().notNull(),
+  deploymentId: text('deployment_id').notNull(),
+})
+export const accessBootstrap = pgTable(
+  'access_bootstrap',
+  {
+    id: integer('id').primaryKey(),
+    initializedAdminUserId: uuid('initialized_admin_user_id')
+      .notNull()
+      .references(() => users.id),
+    initializedAt: timestamp('initialized_at', { withTimezone: true }).defaultNow().notNull(),
+  },
+  /**
+   * 将初始化状态限制为 ID 为 1 的单例记录，避免重复保存引导状态。
+   */
+  (t) => [check('access_bootstrap_singleton', sql`${t.id} = 1`)],
+)

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

@@ -14,6 +14,9 @@ export type DrizzleDB = NodePgDatabase<typeof schema>
     {
       provide: DRIZZLE,
       inject: [ConfigService],
+      /**
+       * 根据数据库配置创建 PostgreSQL 连接池，并绑定表结构生成可注入的 Drizzle 客户端。
+       */
       useFactory: (config: ConfigService) => {
         const pool = new Pool({
           host: config.get<string>('database.host'),