create-bubbles 0.1.26 → 0.1.27

package/template-vp-monorepo-react-nestjs/apps/server/test/auth/password.integration.spec.ts

@@ -0,0 +1,300 @@
+import 'reflect-metadata'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vite-plus/test'
+import { ConfigService } from '@nestjs/config'
+import { eq } from 'drizzle-orm'
+import { drizzle } from 'drizzle-orm/node-postgres'
+import { migrate } from 'drizzle-orm/node-postgres/migrator'
+import Redis from 'ioredis'
+import { Pool } from 'pg'
+import { randomUUID } from 'node:crypto'
+import * as schema from '@/database/schema'
+import { ACCESS_ERRORS } from '@/modules/access/access.errors'
+import { AccessService } from '@/modules/access/access.service'
+import { AccessSeedService } from '@/modules/access/seed/access-seed.service'
+import { AUTH_ERRORS } from '@/modules/auth/auth.errors'
+import { AuthRepository } from '@/modules/auth/auth.repository'
+import { AuthService } from '@/modules/auth/auth.service'
+import { PasswordService } from '@/modules/auth/password.service'
+import { SessionStoreService } from '@/modules/auth/session/session-store.service'
+import { SessionTokenService } from '@/modules/auth/session/session-token.service'
+import { AccountPasswordResetService } from '@/modules/members/accounts/password-reset/password-reset.service'
+import type { SessionTerminalType } from 'shared/types'
+
+const enabled = process.env.RUN_PASSWORD_INTEGRATION === 'true'
+const databaseName = `password_it_${randomUUID().replaceAll('-', '')}`
+const originalPassword = 'qaOld12345'
+const changedPassword = 'qaNew12345'
+const resetPassword = 'qaReset123'
+const terminals: SessionTerminalType[] = ['web', 'mobile', 'desktop']
+
+describe.skipIf(!enabled)('密码操作真实 PostgreSQL / Redis 集成', () => {
+  let adminPool: Pool
+  let pool: Pool
+  let redis: Redis
+  let db: ReturnType<typeof drizzle<typeof schema>>
+  let passwords: PasswordService
+  let sessions: SessionStoreService
+  let tokens: SessionTokenService
+  let auth: AuthService
+  let reset: AccountPasswordResetService
+  let admin: typeof schema.users.$inferSelect
+  const userIds: string[] = []
+
+  /** 仅允许对本机开发容器创建随机数据库，并使用独立 Redis 逻辑库。 */
+  function assertIsolatedEnvironment(): string {
+    const connectionString = process.env.DATABASE_URL
+    if (!connectionString) throw new Error('缺少隔离测试 DATABASE_URL')
+    const url = new URL(connectionString)
+    if (
+      !['127.0.0.1', 'localhost'].includes(url.hostname) ||
+      url.port !== '5432' ||
+      url.pathname !== '/postgres' ||
+      !['127.0.0.1', 'localhost'].includes(process.env.REDIS_HOST ?? '') ||
+      process.env.REDIS_PORT !== '6379' ||
+      process.env.REDIS_DB !== '15'
+    ) {
+      throw new Error('拒绝运行：仅允许本机开发容器和 Redis DB 15')
+    }
+    return connectionString
+  }
+
+  /** 在随机临时数据库中创建没有工作空间关系的账号。 */
+  async function createUser(label: string) {
+    const account = `pwit_${label}_${randomUUID().replaceAll('-', '').slice(0, 10)}`
+    const [user] = await db
+      .insert(schema.users)
+      .values({ account, name: label, passwordHash: await passwords.hash(originalPassword) })
+      .returning()
+    userIds.push(user!.id)
+    return user!
+  }
+
+  /** 在真实 Redis 中建立同一账号的三个终端会话，并返回不含明文令牌的摘要。 */
+  async function createTerminalSessions(userId: string) {
+    const digests: string[] = []
+    for (const terminal of terminals) {
+      const { tokenDigest } = tokens.createToken()
+      await sessions.createOrReplace({
+        userId,
+        terminal,
+        tokenDigest,
+        loginIp: '127.0.0.1',
+        userAgent: `integration-${terminal}`,
+      })
+      digests.push(tokenDigest)
+    }
+    return digests
+  }
+
+  /** 读取当前账号摘要，用于确认真实数据库事务已提交或回滚。 */
+  async function passwordHash(userId: string) {
+    const [user] = await db
+      .select({ passwordHash: schema.users.passwordHash })
+      .from(schema.users)
+      .where(eq(schema.users.id, userId))
+    return user!.passwordHash
+  }
+
+  /** 检查测试创建的全部终端令牌是否仍能通过真实 Redis Lua 校验。 */
+  async function expectSessions(digests: string[], userId: string, valid: boolean) {
+    for (const [index, digest] of digests.entries()) {
+      const current = await sessions.validateAndTouch(digest)
+      if (valid) expect(current).toEqual({ userId, terminal: terminals[index] })
+      else expect(current).toBeNull()
+    }
+  }
+
+  beforeAll(async () => {
+    const connectionString = assertIsolatedEnvironment()
+    adminPool = new Pool({ connectionString })
+    await adminPool.query(`CREATE DATABASE "${databaseName}"`)
+    const testUrl = new URL(connectionString)
+    testUrl.pathname = `/${databaseName}`
+    pool = new Pool({ connectionString: testUrl.toString(), max: 6 })
+    db = drizzle(pool, { schema })
+    await migrate(db, { migrationsFolder: './drizzle' })
+
+    redis = new Redis({
+      protocol: 2,
+      host: process.env.REDIS_HOST,
+      port: Number(process.env.REDIS_PORT),
+      password: process.env.REDIS_PASSWORD || undefined,
+      db: 15,
+      lazyConnect: true,
+    })
+    await redis.connect()
+    const config = new ConfigService({
+      session: {
+        idleTtlMs: 60_000,
+        absoluteTtlMs: 120_000,
+        tokenPepper: 'integration-only-token-pepper-32-bytes',
+      },
+    })
+    passwords = new PasswordService()
+    sessions = new SessionStoreService(redis, config)
+    tokens = new SessionTokenService(config)
+    auth = new AuthService(new AuthRepository(db), passwords, tokens, sessions, config)
+    const access = new AccessService(db)
+    reset = new AccountPasswordResetService(access, passwords, sessions)
+    admin = await createUser('admin')
+    await new AccessSeedService(db).initialize(admin.account)
+  }, 90_000)
+
+  afterAll(async () => {
+    try {
+      if (sessions) {
+        for (const userId of userIds) await sessions.revokeAllForUser(userId)
+      }
+    } finally {
+      if (redis) redis.disconnect()
+      if (pool) await pool.end()
+      if (adminPool) {
+        try {
+          await adminPool.query(`DROP DATABASE IF EXISTS "${databaseName}" WITH (FORCE)`)
+        } finally {
+          await adminPool.end()
+        }
+      }
+    }
+  }, 30_000)
+
+  it('本人改密提交后原密码失效，三个终端会话均撤销', async () => {
+    const user = await createUser('self_success')
+    const digests = await createTerminalSessions(user.id)
+    const before = await passwordHash(user.id)
+
+    await expect(
+      auth.changePassword(user.id, {
+        oldPassword: originalPassword,
+        newPassword: changedPassword,
+        confirmPassword: changedPassword,
+      }),
+    ).resolves.toEqual({ passwordChanged: true })
+
+    expect(await passwordHash(user.id)).not.toBe(before)
+    await expectSessions(digests, user.id, false)
+    await expect(
+      auth.login(
+        { account: user.account, password: originalPassword },
+        { ip: '127.0.0.1', userAgent: 'web' },
+      ),
+    ).rejects.toMatchObject({ definition: AUTH_ERRORS.INVALID_CREDENTIALS })
+    await expect(
+      auth.login(
+        { account: user.account, password: changedPassword },
+        { ip: '127.0.0.1', userAgent: 'web' },
+      ),
+    ).resolves.toMatchObject({ tokenType: 'Bearer' })
+  }, 30_000)
+
+  it('本人改密撤销依赖失败时真实数据库回滚，原会话仍有效', async () => {
+    const user = await createUser('self_rollback')
+    const digests = await createTerminalSessions(user.id)
+    const before = await passwordHash(user.id)
+    const revoke = vi
+      .spyOn(sessions, 'revokeAllForUser')
+      .mockRejectedValueOnce(new Error('injected Redis failure'))
+    try {
+      await expect(
+        auth.changePassword(user.id, {
+          oldPassword: originalPassword,
+          newPassword: changedPassword,
+          confirmPassword: changedPassword,
+        }),
+      ).rejects.toMatchObject({ definition: AUTH_ERRORS.SERVICE_UNAVAILABLE })
+    } finally {
+      revoke.mockRestore()
+    }
+
+    expect(await passwordHash(user.id)).toBe(before)
+    await expectSessions(digests, user.id, true)
+  }, 30_000)
+
+  it('平台管理员重置仅影响目标摘要与三个终端会话，管理员会话保持有效', async () => {
+    const target = await createUser('reset_success')
+    const targetDigests = await createTerminalSessions(target.id)
+    const [adminDigest] = await createTerminalSessions(admin.id)
+    const before = await passwordHash(target.id)
+
+    await expect(
+      reset.resetPassword({
+        actor: { userId: admin.id, requestId: randomUUID() },
+        userId: target.id,
+        body: { newPassword: resetPassword, confirmPassword: resetPassword },
+      }),
+    ).resolves.toEqual({ passwordReset: true })
+
+    expect(await passwordHash(target.id)).not.toBe(before)
+    await expectSessions(targetDigests, target.id, false)
+    expect(await sessions.validateAndTouch(adminDigest!)).toEqual({
+      userId: admin.id,
+      terminal: 'web',
+    })
+    const [saved] = await db.select().from(schema.users).where(eq(schema.users.id, target.id))
+    expect(saved?.status).toBe('active')
+    const audit = await db
+      .select()
+      .from(schema.auditLogs)
+      .where(eq(schema.auditLogs.objectId, target.id))
+    expect(audit.filter((entry) => entry.action === 'account.password.reset')).toMatchObject([
+      { actorUserId: admin.id, objectId: target.id, summary: { result: 'success' } },
+    ])
+    await expect(
+      auth.login(
+        { account: target.account, password: originalPassword },
+        { ip: '127.0.0.1', userAgent: 'web' },
+      ),
+    ).rejects.toMatchObject({ definition: AUTH_ERRORS.INVALID_CREDENTIALS })
+    await expect(
+      auth.login(
+        { account: target.account, password: resetPassword },
+        { ip: '127.0.0.1', userAgent: 'web' },
+      ),
+    ).resolves.toMatchObject({ tokenType: 'Bearer' })
+  }, 30_000)
+
+  it('管理员重置撤销依赖失败时摘要与成功审计回滚，目标和管理员会话均有效', async () => {
+    const target = await createUser('reset_rollback')
+    const targetDigests = await createTerminalSessions(target.id)
+    const [adminDigest] = await createTerminalSessions(admin.id)
+    const before = await passwordHash(target.id)
+    const revoke = vi
+      .spyOn(sessions, 'revokeAllForUser')
+      .mockRejectedValueOnce(new Error('injected Redis failure'))
+    try {
+      await expect(
+        reset.resetPassword({
+          actor: { userId: admin.id, requestId: randomUUID() },
+          userId: target.id,
+          body: { newPassword: resetPassword, confirmPassword: resetPassword },
+        }),
+      ).rejects.toMatchObject({ definition: AUTH_ERRORS.SERVICE_UNAVAILABLE })
+    } finally {
+      revoke.mockRestore()
+    }
+
+    expect(await passwordHash(target.id)).toBe(before)
+    await expectSessions(targetDigests, target.id, true)
+    expect(await sessions.validateAndTouch(adminDigest!)).toEqual({
+      userId: admin.id,
+      terminal: 'web',
+    })
+    const audit = await db
+      .select()
+      .from(schema.auditLogs)
+      .where(eq(schema.auditLogs.objectId, target.id))
+    expect(audit.filter((entry) => entry.action === 'account.password.reset')).toHaveLength(0)
+  }, 30_000)
+
+  it('平台管理员不能通过重置入口重置自己的密码', async () => {
+    const before = await passwordHash(admin.id)
+    await expect(
+      reset.resetPassword({
+        actor: { userId: admin.id, requestId: randomUUID() },
+        userId: admin.id,
+        body: { newPassword: resetPassword, confirmPassword: resetPassword },
+      }),
+    ).rejects.toMatchObject({ definition: ACCESS_ERRORS.FORBIDDEN })
+    expect(await passwordHash(admin.id)).toBe(before)
+  })
+})

package/template-vp-monorepo-react-nestjs/apps/server/test/error-catalog.spec.ts

@@ -1,8 +1,13 @@
 import { COMMON_ERRORS } from '@/common/error/common.error'
 import { AUTH_ERRORS } from '@/modules/auth/auth.errors'
+import { ACCESS_ERRORS } from '@/modules/access/access.errors'
 import { describe, expect, it } from 'vite-plus/test'
 
-const definitions = [...Object.values(COMMON_ERRORS), ...Object.values(AUTH_ERRORS)]
+const definitions = [
+  ...Object.values(COMMON_ERRORS),
+  ...Object.values(AUTH_ERRORS),
+  ...Object.values(ACCESS_ERRORS),
+]
 
 describe('error catalog', () => {
   it('uses valid and globally unique error codes', () => {

package/template-vp-monorepo-react-nestjs/apps/server/test/menus.validation.spec.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vite-plus/test'
+import { createMenuSchema } from '@/modules/menus/menus.validation'
+
+const baseMenu = {
+  expectedVersion: 1,
+  type: 'directory' as const,
+  parentId: null,
+  name: '自定义目录',
+}
+
+describe('菜单图标 key 校验', () => {
+  it('允许空值、稳定 SVG key 和子目录 key', () => {
+    for (const icon of ['', 'organization-template', 'admin/overview']) {
+      expect(createMenuSchema.parse({ ...baseMenu, icon }).icon).toBe(icon)
+    }
+  })
+
+  it('拒绝 URL、路径穿越、HTML 和旧 Ant Design 图标名', () => {
+    for (const icon of [
+      'https://example.invalid/icon.svg',
+      '../menu-item',
+      '<svg>',
+      'MenuOutlined',
+    ]) {
+      expect(() => createMenuSchema.parse({ ...baseMenu, icon })).toThrow()
+    }
+  })
+})

package/template-vp-monorepo-react-nestjs/apps/server/test/organization/organization-domain.spec.ts

@@ -0,0 +1,260 @@
+import { describe, expect, it } from 'vite-plus/test'
+import {
+  deriveOrganizationUnits,
+  nextOrganizationSort,
+  type OrganizationUnitRow,
+} from '@/modules/organization/organization.store'
+import {
+  cloneTemplateSnapshot,
+  prepareTemplateDefinition,
+} from '@/modules/organization/templates/organization-templates.store'
+import { identityInCandidateFilterDomain } from '@/modules/organization/candidates/member-candidates.service'
+import type { OrganizationMemberIdentity } from 'shared/types'
+import { ORGANIZATION_MAX_SORT, organizationMemberCandidateQuerySchema } from 'shared/utils'
+
+const timestamp = new Date('2026-01-01T00:00:00.000Z')
+
+/** 创建仅供组织树派生测试使用的完整数据库记录。 */
+function unit(input: {
+  id: string
+  parentId: string | null
+  name: string
+  status?: 'active' | 'disabled'
+}): OrganizationUnitRow {
+  return {
+    id: input.id,
+    treeId: 'tree',
+    parentId: input.parentId,
+    name: input.name,
+    nameKey: input.name.toLowerCase(),
+    code: input.id,
+    codeKey: input.id,
+    description: '',
+    sort: 1,
+    status: input.status ?? 'active',
+    version: 1,
+    sourceTemplateUnitId: null,
+    createdAt: timestamp,
+    updatedAt: timestamp,
+  }
+}
+
+describe('组织领域纯函数', () => {
+  it('把真实 GET Query 的单值、逗号字符串和重复参数数组规范化为 UUID 数组', () => {
+    const firstId = crypto.randomUUID()
+    const secondId = crypto.randomUUID()
+    const filterFields = ['organizationUnitIds', 'positionIds', 'roleIds', 'projectIds'] as const
+
+    for (const field of filterFields) {
+      expect(organizationMemberCandidateQuerySchema.parse({ [field]: firstId })[field]).toEqual([
+        firstId,
+      ])
+    }
+    expect(
+      organizationMemberCandidateQuerySchema.parse({
+        positionIds: `${firstId},${secondId}`,
+      }).positionIds,
+    ).toEqual([firstId, secondId])
+    expect(
+      organizationMemberCandidateQuerySchema.parse({
+        positionIds: [firstId, secondId],
+      }).positionIds,
+    ).toEqual([firstId, secondId])
+  })
+
+  it('GET Query 候选 ID 在规范化后仍拒绝重复值和超过一百项', () => {
+    const id = crypto.randomUUID()
+    expect(
+      organizationMemberCandidateQuerySchema.safeParse({ positionIds: `${id},${id}` }).success,
+    ).toBe(false)
+    expect(
+      organizationMemberCandidateQuerySchema.safeParse({
+        positionIds: Array.from({ length: 101 }, () => crypto.randomUUID()).join(','),
+      }).success,
+    ).toBe(false)
+  })
+
+  it('派生路径、深度、有效状态和直接子节点标记', () => {
+    const derived = deriveOrganizationUnits([
+      unit({ id: 'root', parentId: null, name: '集团', status: 'disabled' }),
+      unit({ id: 'company', parentId: 'root', name: '甲企业' }),
+      unit({ id: 'finance', parentId: 'company', name: '财务部' }),
+    ])
+
+    expect(derived.get('root')).toMatchObject({
+      depth: 1,
+      fullPath: '集团',
+      effective: false,
+      hasChildren: true,
+    })
+    expect(derived.get('finance')).toEqual({
+      depth: 3,
+      fullPath: '集团 / 甲企业 / 财务部',
+      effective: false,
+      hasChildren: false,
+    })
+  })
+
+  it('同级排序从 1 开始并在整数上限耗尽时拒绝递增', () => {
+    expect(nextOrganizationSort([])).toBe(1)
+    expect(nextOrganizationSort([{ sort: 2 }, { sort: 8 }])).toBe(9)
+    expect(() => nextOrganizationSort([{ sort: ORGANIZATION_MAX_SORT }])).toThrow()
+  })
+
+  it('拒绝模板中重复 clientKey 和缺失父节点', () => {
+    expect(() =>
+      prepareTemplateDefinition({
+        units: [
+          {
+            clientKey: 'same',
+            parentClientKey: null,
+            name: '组织一',
+            code: 'unit-1',
+            sort: 1,
+          },
+          {
+            clientKey: 'same',
+            parentClientKey: null,
+            name: '组织二',
+            code: 'unit-2',
+            sort: 2,
+          },
+        ],
+        positions: [],
+      }),
+    ).toThrow()
+    expect(() =>
+      prepareTemplateDefinition({
+        units: [
+          {
+            clientKey: 'child',
+            parentClientKey: 'missing',
+            name: '子组织',
+            code: 'child',
+            sort: 1,
+          },
+        ],
+        positions: [],
+      }),
+    ).toThrow()
+  })
+
+  it('拒绝模板父引用循环和超过十层的组织树', () => {
+    expect(() =>
+      prepareTemplateDefinition({
+        units: [
+          {
+            clientKey: 'a',
+            parentClientKey: 'b',
+            name: '组织甲',
+            code: 'unit-a',
+            sort: 1,
+          },
+          {
+            clientKey: 'b',
+            parentClientKey: 'a',
+            name: '组织乙',
+            code: 'unit-b',
+            sort: 2,
+          },
+        ],
+        positions: [],
+      }),
+    ).toThrow()
+    expect(() =>
+      prepareTemplateDefinition({
+        units: Array.from({ length: 11 }, (_, index) => ({
+          clientKey: `unit-${index}`,
+          parentClientKey: index === 0 ? null : `unit-${index - 1}`,
+          name: `组织${index + 1}`,
+          code: `unit-${index}`,
+          sort: index,
+        })),
+        positions: [],
+      }),
+    ).toThrow()
+  })
+
+  it('复制模板快照时生成新 ID 并重新映射父子关系', () => {
+    const snapshot = cloneTemplateSnapshot({
+      units: [
+        {
+          id: 'old-root',
+          parentId: null,
+          name: '集团',
+          nameKey: '集团',
+          code: 'group',
+          codeKey: 'group',
+          description: '',
+          sort: 1,
+        },
+        {
+          id: 'old-child',
+          parentId: 'old-root',
+          name: '财务部',
+          nameKey: '财务部',
+          code: 'finance',
+          codeKey: 'finance',
+          description: '',
+          sort: 2,
+        },
+      ],
+      positions: [
+        {
+          name: '会计',
+          nameKey: '会计',
+          code: 'accountant',
+          codeKey: 'accountant',
+          description: '',
+          status: 'active',
+        },
+      ],
+    })
+
+    expect(snapshot.units[0]?.id).not.toBe('old-root')
+    expect(snapshot.units[1]?.id).not.toBe('old-child')
+    expect(snapshot.units[1]?.parentId).toBe(snapshot.units[0]?.id)
+    expect(snapshot.positions[0]?.id).toBeTruthy()
+  })
+
+  it('企业候选未指定项目时只让企业身份参与筛选', () => {
+    const companyIdentity = {
+      scope: { type: 'company', companyId: 'company-1' },
+      scopeName: '甲企业',
+      memberId: 'company-member',
+      memberStatus: 'active',
+      scopeStatus: 'active',
+      organizationUnits: [],
+      positions: [],
+      roles: [],
+    } satisfies OrganizationMemberIdentity
+    const projectIdentity = {
+      ...companyIdentity,
+      scope: { type: 'project', companyId: 'company-1', projectId: 'project-1' },
+      scopeName: '项目一',
+      memberId: 'project-member',
+    } satisfies OrganizationMemberIdentity
+
+    expect(
+      identityInCandidateFilterDomain(
+        companyIdentity,
+        { type: 'company', companyId: 'company-1' },
+        {},
+      ),
+    ).toBe(true)
+    expect(
+      identityInCandidateFilterDomain(
+        projectIdentity,
+        { type: 'company', companyId: 'company-1' },
+        {},
+      ),
+    ).toBe(false)
+    expect(
+      identityInCandidateFilterDomain(
+        projectIdentity,
+        { type: 'company', companyId: 'company-1' },
+        { projectIds: ['project-1'] },
+      ),
+    ).toBe(true)
+  })
+})

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

@@ -0,0 +1,5 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": { "rootDir": "." },
+  "include": ["src/**/*.ts"]
+}

package/template-vp-monorepo-react-nestjs/apps/web/.agents/rules//347/273/204/344/273/266/345/244/215/347/224/250.md

@@ -0,0 +1,7 @@
+# 组件复用与静态内容
+
+- 开始新增或修改页面、布局或 React 组件前，先检查是否已有可复用组件，并识别页面结构中可复用的展示或交互，再根据全部引用方的实际范围确定组件归属。
+- 供整个前端应用复用的组件统一放在 `@/components`。该目录优先放置跨页面、低业务耦合且接口稳定的通用组件。
+- 只在局部范围复用的组件放在所有引用方最近公共祖先目录下的 `components` 中。组件新增了该目录之外的引用方时，须重新计算最近公共祖先，将组件移动到新公共范围对应的 `components`，并同步更新引用；复用范围扩展到整个应用时，移动到 `@/components`。
+- 不依赖父组件本次渲染局部值的静态常量、配置和 JSX 放在 React 组件函数外。小且仅属于当前页面的内容可放在同一文件的模块顶层；较多配置抽离到当前功能目录的 `config/index.ts`、`config/index.tsx` 或其他职责明确的配置文件；具有独立 UI 职责或适合复用的内容抽成 `components/<ComponentName>`。
+- 在 React 组件函数内声明的子组件须移到函数外或相应的 `components` 目录；需要父组件的数据或回调时，通过 props 显式传入。

package/template-vp-monorepo-react-nestjs/apps/web/.agents/rules//350/241/250/345/215/225/345/233/236/345/241/253.md

@@ -0,0 +1,4 @@
+# 表单回填
+
+- 开启浏览器回填（自动填充）的输入框，必须为 `:autofill`/`:-webkit-autofill`（含 `:hover`、`:focus`、`:active`）状态设置 `transition: background-color 900000000s ease-in-out 0s;`，冻结浏览器注入的填充底色，保持输入框自身底色；该底色是带 `!important` 的 UA 样式，普通背景声明无法覆盖。
+- 填充态文字色用 `-webkit-text-fill-color` 指定，并显式设置 `caret-color` 保证光标可见。

package/template-vp-monorepo-react-nestjs/apps/web/AGENTS.md

@@ -2,15 +2,24 @@
 
 本文件适用于 `apps/web` 及其子目录，同时遵循[根目录 AGENTS.md](../../AGENTS.md)中的通用规则。
 
+## 自动导入
+
+- `react`、`react-router`、`react-dom` 的 API 和类型通过 `unplugin-auto-import` 自动导入，业务代码和测试不再手动导入这些包；`react-dom/client` 的 `createRoot` 同样自动导入。
+- 使用尚未覆盖的 API 或类型时，先补充 `vite.config.ts` 的自动导入配置，再由插件更新 `src/types/auto-imports.d.ts`，不要手动修改生成声明。
+- 同名 API 必须配置明确的别名：React 的 `createContext` 保持原名，React Router 的 `createContext` 使用 `createRouterContext`，避免上下文类型混用。
+- React 的 `ViewTransition` 使用 `ReactViewTransition` 别名，避免与浏览器原生 `ViewTransition` 全局类型冲突。
+
 ## 按需规则
 
 根据当前任务匹配下表，在执行相关操作前读取对应规则；命中多项时分别读取。不要预先加载整个 `.agents/rules/` 目录；任务范围变化时补读新命中的规则。
 
-| 适用条件                                                           | 规则文件                              |
-| ------------------------------------------------------------------ | ------------------------------------- |
-| 当前修改的 Web 代码文件已超过或将超过 300 行                       | [文件拆分](.agents/rules/文件拆分.md) |
-| 新增、修改或移动页面相关的 API 请求代码                            | [页面接口](.agents/rules/页面接口.md) |
-| 新增、修改、移动或重命名 `components` 下的组件文件、组件目录或组件 | [组件命名](.agents/rules/组件命名.md) |
-| 新增、封装或修改弹窗组件，或调整其打开、关闭及传参方式             | [弹窗组件](.agents/rules/弹窗组件.md) |
-| 新增、修改或重构表格类增删改查列表页面（含草稿功能）               | [表格页面](.agents/rules/表格页面.md) |
-| 新增、修改或使用 SVG                                               | [SVG 使用](.agents/rules/SVG使用.md)  |
+| 适用条件                                                            | 规则文件                              |
+| ------------------------------------------------------------------- | ------------------------------------- |
+| 当前修改的 Web 代码文件已超过或将超过 300 行                        | [文件拆分](.agents/rules/文件拆分.md) |
+| 新增、修改或移动页面相关的 API 请求代码                             | [页面接口](.agents/rules/页面接口.md) |
+| 新增、修改、抽取或移动 React 组件，或调整组件复用范围与静态内容放置 | [组件复用](.agents/rules/组件复用.md) |
+| 新增、修改、移动或重命名 `components` 下的组件文件、组件目录或组件  | [组件命名](.agents/rules/组件命名.md) |
+| 新增、封装或修改弹窗组件，或调整其打开、关闭及传参方式              | [弹窗组件](.agents/rules/弹窗组件.md) |
+| 新增、修改或重构表格类增删改查列表页面（含草稿功能）                | [表格页面](.agents/rules/表格页面.md) |
+| 新增、修改或使用 SVG                                                | [SVG 使用](.agents/rules/SVG使用.md)  |
+| 新增、修改开启浏览器回填（自动填充）的表单或输入框                  | [表单回填](.agents/rules/表单回填.md) |