SuperAPI AI 工具集

worldcrafter-feature-builder

编程与开发

查看项目

更新于 11-14 00:52

技能介绍

WorldCrafter Feature Builder 是一个用于在 WorldCrafter 代码库中实现新功能的技能(版本 2.0.0,最后更新 2025-01-15)。它按照项目既定的架构模式、最佳实践和测试标准,给出一套按阶段推进的功能实现流程。

主要用途: 向应用新增功能;构建带校验和 Server Actions 的表单;为新资源创建 CRUD 操作;实现需要认证的工作流;添加需要数据库操作的功能;以及构建包含单元测试、集成测试和 E2E 测试的功能。

实现流程:

  • 需求收集:明确功能用途、用户交互、是否需要认证、需要存取的数据和校验要求,并规划数据库变更(新增表或列、表间关系、RLS 策略)。
  • 脚手架生成:运行 python .claude/skills/worldcrafter-feature-builder/scripts/scaffold_feature.py <feature-name> 生成页面组件、actions.ts、loading.tsx、error.tsx、Zod Schema、集成测试和 E2E 测试文件,也可以手动复制 assets/templates/ 中的模板。
  • 数据库层:在 prisma/schema.prisma 中新增模型和关系,执行 npx prisma migrate dev --name add_<feature_name> 创建迁移,编写 RLS 策略 SQL 并运行 npm run db:rls,再用 npm run db:test:sync 同步测试数据库。
  • 校验层:在 src/lib/schemas/<feature-name>.ts 中定义 Zod 校验规则并导出 TypeScript 类型,覆盖邮箱、必填字符串、可选字段、枚举、数字区间、日期等常见模式。
  • Server Actions:在 actions.ts 中使用 "use server" 指令,按“校验、认证、数据库操作、revalidatePath、返回结果”的顺序实现,并遵循安全清单(Zod 校验、认证检查、资源归属校验、参数化查询、不暴露敏感数据)。
  • 客户端组件:使用 React Hook Form 配合 zodResolver,引用 shadcn/ui 组件,调用 Server Action 并处理加载与错误状态,必要时通过 npx shadcn@latest add [component-name] 添加组件。
  • 加载与错误状态:提供骨架屏 loading.tsx 和带重置功能的客户端 error.tsx。
  • 测试:编写针对 Server Action 与真实测试数据库的集成测试和覆盖完整用户流程的 E2E 测试,运行方式为 npm test、npm run test:coverage、npm run test:e2e、npm run test:all。
  • 最终检查:执行 npm run build、npm run lint、npm run format,并在 Schema 变更后同步测试数据库,确认测试通过。

高级模式(v2.0):

  • 多步表单向导:用于复杂实体创建(如角色创建),每一步使用独立的 Zod Schema 做增量校验,用状态累积各步数据,并展示进度条、提供上一步和下一步导航。
  • Supabase Storage 图片上传:生成唯一文件名上传到指定 bucket,获取公开 URL 回填表单,并配合 Image 组件预览;需要在 Supabase 控制台创建 bucket 并配置公开访问或 RLS 策略。
  • 自定义 JSON 属性:用 Prisma 的 Json 字段存储随世界类型变化的属性,并按类型定义不同的 Zod 子 Schema 做运行时校验。

相关技能:需要新数据库表时先使用 worldcrafter-database-setup;为生成的功能添加认证时使用 worldcrafter-auth-guard;为已有功能补测试时使用 worldcrafter-test-generator;不需要表单的简单页面可以使用 worldcrafter-route-creator。

限制:该技能绑定 WorldCrafter 项目的目录结构与技术栈(Next.js、Prisma、Supabase、shadcn/ui、React Hook Form、Zod),脱离该代码库时,模板和脚本可能无法直接使用。关于收费、价格和具体平台支持范围,资料未提供。