nuxt-app/AGENTS.md

AI八荣八耻

1. Shame in guessing APIs, Honor in careful research.
2. Shame in vague execution, Honor in seeking confirmation.
3. Shame in assuming business logic, Honor in human verification.
4. Shame in creating interfaces, Honor in reusing existing ones.
5. Shame in skipping validation, Honor in proactive testing.
6. Shame in breaking architecture, Honor in following specifications.
7. Shame in pretending to understand, Honor in honest ignorance.
8. Shame in blind modification, Honor in careful refactoring.

必须遵循

• 注意代码的解耦，做到高内聚，低耦合
• 安装依赖时，必须写死依赖的版本，禁止任何升级的可能，如存在需要升级的场景，必须手动执行安装新版本命令
• 新建的mono包必须在根目录安装
• 使用nuxt时遇到不清楚的，必须先加载nuxt-remote查询文档再进行分析
• 能够用toast提示的尽量用toast
• 数据库schema编写完成之后，必须使用命令进行迁移，不能自己生成

代码抽离与复用

• 编写任何前端组件/工具函数时，必须评估是否可以抽离为通用模块，加入对应 packages（bolt-ui、common 等）
• bolt-ui 只放基础通用 UI 组件（Button、Input、Modal、Container 等），业务相关组件留在 app/components/
• 开发时随时查看 bolt-ui 已有组件（Button、ConfigProvider、Container 等），优先复用，避免重复造轮子
• 新增 bolt-ui 组件需遵循现有模式：components/<Name>/src/<Name>.vue + index.ts（使用 withInstall 注册），并在 components/index.ts 中导出
• 必须时刻注意bolt-ui中readme.md的更新

设计方案

开发页面与组件时必须参考 DESIGN.md

E2E 测试

架构

• 框架：Playwright 1.49.1 + @nuxt/test-utils 3.15.4
• 测试目录：e2e/（specs/、helpers/、fixtures/）
• 测试服务器：build + preview 模式，global-setup.ts 自动执行 build → migrate → seed → spawn server
• 数据库隔离：独立 SQLite 文件 packages/drizzle-pkg/db.test.sqlite，workers=1 避免并发
• 验证码注入：业务代码分支方式，server/service/captcha/challenge.ts 中 E2E_TEST_MODE 门控返回固定验证码
• 环境变量：.env.test 文件，由 global-setup.ts 和 playwright.config.ts 内部代码解析注入

运行命令

bun run test:e2e          # 运行全部 E2E 测试（headless）
bun run test:e2e:headed   # 有头模式运行
bun run test:e2e:ui       # Playwright UI 模式

编写测试注意事项

• 用户名规则：/^[a-zA-Z0-9_]{3,20}$/（3-20字符，仅字母数字下划线），生成动态用户名时注意长度
• toHaveURL 匹配完整 URL（含 host），正则应匹配路径结尾而非开头
• 已登录状态测试：通过 UI 登录设置 cookie，不要用 request context（cookie 不共享到 page）
• 避免使用 waitForLoadState("networkidle")，部分页面有持续网络请求会导致超时
• SSR 中间件重定向可能不带 ?redirect= 参数，测试应兼容此情况