Menu
当你修改数据库结构或种子生成脚本时，请务必阅读并遵循此指南，以防止性能问题、数据一致性崩溃和部署失败。新 Schema 应在 apps/type 中创建。
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Baseado na classificação ocupacional SOC
使用 Nitro v3 框架和 H3 编写服务端 API 的技能。适用于后端接口开发、Mock 数据迁移到 Neon 数据库、以及编写符合 Drizzle ORM 标准的查询逻辑。当需要开发新的 CRUD 接口或修复现有后端逻辑时使用此技能。
规范类型项目（apps/type）的代码组织方式、导出语法和文件结构。用于解决类型导出冲突、创建统一导出入口、处理重复导出等问题。适用于类型项目开发、类型错误修复、代码规范实施场景。在处理类型项目的代码写法时，请使用本技能。
数据库 Schema 变更时的全项目同步检查清单。当修改 apps/type 中 schema.ts 的表字段、新增数据库表、或删除表时，使用此技能确保类型项目、数据库迁移、后端接口、前端页面、种子数据和技能文档全部同步更新，避免遗漏。
当用户要求在 bug 已经定位并修复后，记录排错经验、事故结论、AI 记忆更新、复盘摘要或本地 MCP 记忆时使用。这个技能只负责沉淀"发生了什么、为什么会发生、如何修好、以后要记住什么"，不要把它用于实际修复 bug。
新建公共组件规范专家 - 指导在 src/components/common 目录下创建符合项目规范的公共组件，包括文件结构、TypeScript 类型、Vue 组件、文档和测试页面。 触发条件（满足任意一项即触发）： - 任务包含"新建组件"、"公共组件"、"common 组件"、"创建组件"等关键词 - 需要在 src/components/common 目录下创建新组件 - 需要创建可复用的业务组件（如表单分区标题、操作按钮组、信息展示卡片） - 需要编写组件的 TypeScript 类型定义 - 需要编写组件使用文档（index.md） - 需要创建组件测试页面（src/pages/test-use/） - 用户提及"组件规范"、"组件文档"、"组件测试"等关键词 必须协同的技能： - beautiful-component-design（组件美化时）- 图标、响应式设计、表单分区标题 - component-migration（从旧组件迁移时）- ColorUI → wot-design-uni - use-wd-form（组件内包含表单时）- 表单结构、wd-picker、校验规则 禁止事项： - 禁止在 components 目录外创建公共组件 - 禁止不编写组件文档（index.md） - 禁止不提供使用示例和测试页面 - 禁止组件命名不规范（必须使用短横线命名法） - 禁止不定义 TypeScript 类型（types.ts） - 禁止在组件文件顶部不添加说明注释 - 禁止不使用 withDefaults 设置 props 默认值 覆盖场景：所有需要跨页面复用的业务组件，包括表单分区标题（FormSectionTitle）、操作按钮组（ActivityActions）、信息展示卡片（ActivityInfo）、加载状态组件（ZPagingLoading）等。
接口错误提示能力 - 提供统一的接口错误提示标准和实施方案，基于 wot-design-uni 和 Alova useRequest 回调模式。 触发条件（满足任意一项即触发）： - 编写任何 API 接口调用代码（使用 useRequest） - 处理 useRequest 的 onError 回调 - 实现全局错误拦截逻辑 - 用户提及"接口错误提示"、"错误处理"、"Toast 提示"等关键词 - 从 Vue2 迁移 API 调用（需要添加错误处理） - 实现表单提交、列表加载等涉及 API 的功能 必须协同的技能： - api-migration（API 接口迁移时） - z-paging-integration（分页列表时） - use-wd-form（表单提交时） 禁止项： - 禁止使用 try/catch 包装 send() 函数 - 禁止在组件内手动显示错误 Toast（全局拦截器已处理） - 禁止使用 immediate: true（必须手动触发请求） - 禁止在 onError 中重复显示错误提示 覆盖场景：几乎所有 API 调用都需要此技能，包括列表查询、详情查询、表单提交、数据删除、状态更新等。
| name | schema-and-seed-guardian |
| description | 当你修改数据库结构或种子生成脚本时，请务必阅读并遵循此指南，以防止性能问题、数据一致性崩溃和部署失败。新 Schema 应在 apps/type 中创建。 |
[MIGRATION NOTICE] Schema 定义位置正在迁移中:
- 旧位置 (Legacy):
apps/admin/server/db/schemas- 仅供只读参考，新 Schema 应在apps/type/src/business/{domain}/{module}/schema.ts中创建- 新位置 (Active):
apps/type/src/business/**/schema.ts- 所有新 Schema 必须在此创建- 迁移入口 (Active): Drizzle Kit 配置、
drizzle/**迁移目录、db:*脚本、Neon readiness/drift 诊断和受控迁移执行归apps/api；apps/admin只作为 legacy source 或兼容参考。重要: 当你需要添加新列或新表时，应在
apps/type/src/business/{domain}/{module}/schema.ts中创建 Zod Schema + Drizzle Table。
本技能总结了项目在数据库架构变更和种子数据生成方面的血泪经验。请在进行相关开发时严格查阅以下 Checklist。
在修改或新增 Schema 定义时:
apps/type/src/business/**/schema.ts 中创建apps/type/src/business/{domain}/{module}/schema.ts 中维护（仅限已存在的表）风险：如果表使用了软删除（即存在 deletedAt 字段），绝对禁止使用普通的 .uniqueIndex()。
后果：用户删除了记录 A，尝试重新创建相同关键信息的记录 B 时，会被数据库的唯一索引拦截（因为它包含已删除的记录）。
规范：
必须为唯一索引添加部分条件 (WHERE deleted_at IS NULL)。通过 drizzle-orm 的 .where(isNull(table.deletedAt)) 实现。
// 错误示例
uniqueIndex("idx_code").on(table.code);
// 正确示例
import { isNull } from "drizzle-orm";
// ...
(table) => [uniqueIndex("idx_code").on(table.code).where(isNull(table.deletedAt))];
风险：仅定义 ...Id 字段而不建立 .references()。
后果：产生孤儿数据，应用层逻辑复杂化。
规范：
除非是多态关联（一个字段对应多张表），否则必须使用 .references(() => otherTable.id) 建立物理外键。
规范：
在编写或修改 Seed 模块时 (apps/admin/server/db/seed/modules/*.seed.ts)：
db.insert(table).values([...]) 直接插入as any 类型断言sid(scope, key) 基于 uuid v5 生成确定性 IDsid() 调用确保外键一致communityId: sid("community", "sunshine") 在所有模块中生成相同的 UUID"enabled" 而非 toStatusEnum("启用")"approved" 而非 toAuditStatusEnum("已通过")pnpm -F @01s-11comm/api db:generate — 从 apps/type schema 生成 Drizzle 迁移pnpm -F @01s-11comm/api db:migrate — 通过统一 API 子包执行受控迁移以上迁移命令应通过 apps/api 的 DB 运维入口执行。历史 apps/admin seed/reset 脚本若仍存在，只能按 legacy source 或兼容路径处理；在 apps/api 提供专门 seed/reset 能力前，不得把 admin seed/reset 误写成新的长期权威项目。