更新多个技能文档，新增常见陷阱（Gotchas）部分，提供开发过程中需避免的错误及其解决方案，提升开发团队的规范性和效率。同时，更新描述以更清晰地指引使用场景，确保文档内容的准确性和实用性。

.cursor/skills/admin-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: soul-admin-dev
-description: Soul 创业派对管理端开发规范。在 soul-admin/ 下编辑时必遵循。React、Vite、client.ts、/api/admin/*、/api/db/*、Radix UI、鉴权。Use when editing soul-admin, 管理端, React 管理后台.
+description: Trigger when 编辑 soul-admin、管理端、React 后台、调用 admin/db 接口 时必读。React、Vite、client.ts、/api/admin/*、/api/db/*、Radix UI、Toast、禁止 alert。
 ---
 # Soul 创业派对 - 管理端开发 Skill
 
@@ -145,10 +145,28 @@ alert('保存失败')
 
 ---
 
-## 8. 何时使用本 Skill
+## 8. 常见陷阱（Gotchas）
+
+> 从实际失败中积累，持续补充。**千万别这么做**——对 AI 信号更强。
+
+| 陷阱 | 后果 | 正确做法 |
+|------|------|---------|
+| 调用 `/api/miniprogram/*` | 路由互窜、鉴权混乱 | 仅用 `/api/admin/*`、`/api/db/*` |
+| 使用 `alert()`、`window.alert()` | 用户反馈不规范、阻断流程 | 统一用 `@/utils/toast`（success/error/info） |
+| 在 input/textarea 自身上设 padding | 光标截断、布局异常 | 外边包 div，padding 写在容器，input 设 `width:100%` |
+| 可选字段（T 或 undefined）直接赋给必填 T | TS2322 类型错误 | 用 `?? defaultValue` 兜底，如 `t.appId ?? ''` |
+| 接口缺字段但 API 已返回 | 运行时取不到、展示异常 | 在 interface 补 `field?: Type`（如 `isPinned?: boolean`） |
+| useState 的 setter 传 undefined | setter 类型错误 | 传 `value ?? null` 而非裸 `value` |
+| API 映射时 `p.token` 等可能 undefined | 流入 state 导致异常 | `id: p.token ?? p.personId ?? ''`，`label: p.label ?? ''` |
+| 新增管理页忘记加路由/菜单 | 404 或菜单不可见 | 在 `App.tsx` 加 Route，在 `AdminLayout` 的 `menuItems` 加菜单项 |
+
+---
+
+## 9. 何时使用本 Skill
 
 - 在 **soul-admin/** 下新增或修改页面、组件、API 调用时。
 - 在管理端新增任何网络请求时（必须仅使用 admin/db 等管理端路径）。
 - 做提现、用户、订单、内容、配置等后台功能时。
 
 遵循本 Skill 可保证管理端只与 soul-api 的管理端路由对接，避免与小程序接口混用或误用 next-project 接口。
+