القائمة
Zenith Admin 项目专属开发辅助。Use when: 开发新模块、实现 CRUD、新增页面、配置菜单权限、增删改查、新建后台功能、新增管理功能、异步任务、批量操作、任务进度、发布新版本、db migration、seed data、MSW mock、修改现有模块、添加字段。包含完整的 CRUD 代码生成流程（Step 0-11）、异步任务接入、模块修改流程与版本发布流程。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | zenith |
| description | Zenith Admin 项目专属开发辅助。Use when: 开发新模块、实现 CRUD、新增页面、配置菜单权限、增删改查、新建后台功能、新增管理功能、异步任务、批量操作、任务进度、发布新版本、db migration、seed data、MSW mock、修改现有模块、添加字段。包含完整的 CRUD 代码生成流程（Step 0-11）、异步任务接入、模块修改流程与版本发布流程。 |
| argument-hint | 部门管理 CRUD | 公告管理（含 MSW Mock）| 发布 v1.2.0 | 给用户表加字段 |
| user-invocable | true |
你是 Zenith Admin 项目的专属开发辅助 Agent。本项目是一个基于 Hono + React + Drizzle ORM 的全栈后台管理系统，采用 npm monorepo 结构（packages/server + packages/web + packages/shared）。
快速模式：如果用户说「帮我实现一个简单的 XXX 管理，用默认配置」，可以跳过 Step 0 中的可选项（MSW Mock、数据权限、租户隔离等），使用合理默认值直接生成。
在生成任何代码之前，必须先完成 Step 0。
读取 references/step0-checklist.md，通过 vscode_askQuestions 向用户逐项收集信息，展示汇总后用户确认，再进入 Step 1。
Step 0 中必须同时确认以下可选项（决定后续步骤是否执行）：
按顺序执行，每步的代码模板和规范见 crud-backend.md。
| Step | 任务 | 文件 |
|---|---|---|
| 1 | 数据库 Schema | packages/server/src/db/schema/{业务域}.ts（relations 在 relations.ts） |
| 2 | 生成并执行迁移 | npm run db:generate && npm run db:migrate |
| 3 | 共享 Zod Schema | packages/shared/src/validation.ts |
| 4 | 共享 TS Interface | packages/shared/src/types.ts |
| 5 | Service 层 | packages/server/src/services/{业务域}/xxx.service.ts |
| 6 | OpenAPI Route | packages/server/src/routes/{业务域}/xxx.ts |
| 7 | 注册路由 | packages/server/src/index.ts |
Step 7 完成后执行
npm run dev:server冒烟验证，无编译错误再继续。
⚠️ 外呼调用统一走
http-client：任何 service / 路由中向外部发起的 HTTP 请求（OAuth、第三方 API、链接抓取等），必须使用packages/server/src/lib/http-client.ts的httpRequest/httpGet/httpPost等，禁止直接fetch()。详见 crud-backend.md 外呼 HTTP 调用 与 docs/backend/http-client.md。
⚠️ 长耗时/批量操作统一走任务中心：模块包含批量导入、批量处理、报表生成、数据迁移等无法同步完成的操作时，必须通过
packages/server/src/lib/task-center/的registerTaskHandler+submitAsyncTask实现（自带进度/断点续跑/自动重试/取消/行级明细/WS 推送），禁止自建任务表、轮询字段或 setInterval 后台线程。接入模板见 async-tasks.md。
代码模板和规范见 crud-frontend.md。数据获取统一使用 TanStack Query v5（域 hooks + unwrap），禁止手写 loading/fetchXxx/useEffect 拉取模式。
| Step | 任务 | 文件 |
|---|---|---|
| 8a | 域 hooks（查询/变更） | packages/web/src/hooks/queries/xxxs.ts |
| 8b | 页面组件 | packages/web/src/pages/xxx/XxxPage.tsx |
代码模板和规范见 seed-config.md。
| Step | 任务 | 文件 | 条件 |
|---|---|---|---|
| 9 | 菜单/权限配置 | packages/shared/src/seed-data.ts | 总是 |
| 10 | 种子数据 | packages/server/src/db/seed.ts | 总是 |
| 11 | MSW Mock | packages/web/src/mocks/data/xxxs.ts + handlers/xxxs.ts | 仅 Step 0 确认需要时 |
MSW Mock 的详细代码模板见 crud-mock.md。
后端：
npm run build 无报错packages/server/src/index.tslib/dtos/ 中，路由中没有本地 .openapi() 声明c.json() 或 console.*db.* 调用Promise.all 并行执行 count 和 listescapeLike() 转义前端：
hooks/queries/xxxs.ts）：keys 含 all/lists/list(params)/detail(id)，列表查询带 placeholderData: keepPreviousData，mutation onSuccess 统一 invalidateQueries({ queryKey: xxxKeys.all })loading/data state、fetchXxx useCallback、初始拉取 useEffect；表格 loading={listQuery.isFetching}handleSearch/handleReset 显式 invalidateQueries({ queryKey: xxxKeys.lists })（查询必回源）SearchToolbar + ConfigurableTableSearchToolbar 结构化模式，移动端至少露出一个高频搜索/筛选项（优先关键词；无关键词时选最常用且区分度最高的筛选项，如渠道/类型/作用域）、查询、新增等高频入口，其他筛选进底部筛选抽屉，低频操作进更多菜单page-container page-tabs-page；每个 TabPane 内承载本 tab 的工具栏、表格/空状态/面板，tab 相关操作按钮不要放在 TabBar 外侧createOperationColumn 创建；桌面端按需用 desktopInlineKeys 保留高频内联按钮，移动端自动收纳到更多菜单；状态列紧靠操作列左侧也 fixed: 'right'onRefresh={() => void listQuery.refetch()} 和 refreshLoading={listQuery.isFetching}ExportButton，后端已注册导出中心实体，query 使用当前提交的筛选条件labelPosition="left"，closeOnEsc配置：
packages/shared/src/seed-data.ts约束对照： 实现过程中随时查阅 constraints.md。
当需要修改已有模块（加字段、改接口、加关联关系）时，读取 references/module-modification.md 并按其中的 checklist 执行。
当业务包含长耗时操作（批量导入/处理、报表生成、数据迁移、消息群发等）时，读取 references/async-tasks.md，按其中模板接入任务中心（注册 handler → 提交接口 → 前端 useMyAsyncTasks + AsyncTaskProgress）。选型对照表（任务中心 vs 导出中心 vs 系统周期任务 vs cron_jobs vs workflow_jobs）也在该文档中。
遇到构建错误、迁移失败、类型不匹配等问题时，查阅 references/troubleshooting.md。
读取 references/release.md 并严格按其中的步骤执行。