@robsun/create-keystone-app 0.2.15 → 0.4.1

package/template/.claude/skills/keystone-dev/references/GOTCHAS.md

@@ -1,390 +0,0 @@
-# Keystone 开发常见陷阱
-
-> 开发中容易踩的坑和解决方案。
-
-## 后端陷阱
-
-### G1: 菜单/模块不显示
-
-**症状**：模块代码写完，但菜单不出现或 API 404
-
-**原因**：未在配置中启用模块
-
-**解决**：
-```yaml
-# config.yaml
-modules:
-  enabled:
-    - example
-    - your_new_module  # 添加这行
-```
-
-```typescript
-// app.config.ts
-modules: {
-  enabled: ['example', 'your_new_module']  // 添加这里
-}
-```
-
----
-
-### G2: Handler panic: nil pointer
-
-**症状**：调用 API 时服务 panic
-
-**原因**：Handler 或 Service 未初始化
-
-**错误代码**：
-```go
-func (h *Handler) List(c *gin.Context) {
-    items, _ := h.svc.List(c)  // h.svc 可能为 nil
-}
-```
-
-**正确代码**：
-```go
-func (h *Handler) List(c *gin.Context) {
-    if h == nil || h.svc == nil {
-        response.ServiceUnavailableI18n(c, modulei18n.MsgServiceUnavailable)
-        return
-    }
-    // ...
-}
-```
-
----
-
-### G3: 数据跨租户泄露
-
-**症状**：用户能看到其他租户的数据
-
-**原因**：Repository 查询缺少租户过滤
-
-**错误代码**：
-```go
-func (r *Repository) List(ctx context.Context) ([]Entity, error) {
-    var items []Entity
-    r.db.Find(&items)  // 未过滤租户
-    return items, nil
-}
-```
-
-**正确代码**：
-```go
-func (r *Repository) List(ctx context.Context, tenantID uint) ([]Entity, error) {
-    var items []Entity
-    r.db.Where("tenant_id = ?", tenantID).Find(&items)
-    return items, nil
-}
-```
-
----
-
-### G4: 翻译键显示为原始键
-
-**症状**：界面显示 `example.item.created` 而非翻译文本
-
-**原因**：
-1. 未调用 `RegisterI18n()`
-2. 翻译 JSON 文件路径错误
-3. 键名不匹配
-
-**检查**：
-```go
-// module.go 中必须有
-func (m *Module) RegisterI18n() error {
-    return modulei18n.RegisterLocales()  // 确保调用
-}
-
-// i18n/i18n.go
-//go:embed locales/*.json  // 确保路径正确
-var translations embed.FS
-```
-
----
-
-### G5: GORM 自动更新 UpdatedAt 失效
-
-**症状**：更新记录后 `updated_at` 未变化
-
-**原因**：使用 `Updates()` 时只更新传入字段
-
-**解决**：使用 `Save()` 或显式设置
-```go
-// 方式一：使用 Save
-r.db.Save(entity)
-
-// 方式二：显式更新
-r.db.Model(entity).Updates(map[string]interface{}{
-    "name":       entity.Name,
-    "updated_at": time.Now(),
-})
-```
-
----
-
-### G6: 软删除查不到数据
-
-**症状**：数据库有记录但查询返回空
-
-**原因**：GORM 自动添加 `deleted_at IS NULL` 条件
-
-**解决**：
-```go
-// 查询包含已删除记录
-r.db.Unscoped().Where("id = ?", id).First(&entity)
-
-// 恢复已删除记录
-r.db.Unscoped().Model(&Entity{}).
-    Where("id = ?", id).
-    Update("deleted_at", nil)
-```
-
----
-
-### G7: 循环依赖导致编译失败
-
-**症状**：`import cycle not allowed`
-
-**原因**：service 和 repository 互相导入
-
-**错误结构**：
-```
-service/ → imports → repository/
-repository/ → imports → service/  // 循环!
-```
-
-**解决**：在 service 定义接口，repository 实现
-```go
-// service/service.go
-type EntityRepository interface {
-    FindByID(id uint) (*models.Entity, error)
-}
-
-// repository/repository.go
-// 实现 service.EntityRepository 接口，但不导入 service 包
-```
-
----
-
-## 前端陷阱
-
-### G8: Modal destroyOnClose 无效
-
-**症状**：Modal 关闭后再打开，表单数据残留
-
-**原因**：Ant Design v6 API 变更
-
-**错误代码**：
-```tsx
-<Modal destroyOnClose>  // v6 已废弃
-```
-
-**正确代码**：
-```tsx
-<Modal destroyOnHidden>  // v6 使用这个
-```
-
----
-
-### G9: 翻译不生效
-
-**症状**：`t('key')` 返回 key 本身
-
-**原因**：
-1. 未注册翻译文件
-2. 命名空间错误
-
-**检查**：
-```typescript
-// index.ts 中确保导入翻译文件
-import './locales/zh-CN/module.json'
-import './locales/en-US/module.json'
-
-// 使用时指定正确命名空间
-const { t } = useTranslation('module')  // 不是 'common'
-```
-
----
-
-### G10: API 响应解构错误
-
-**症状**：`TypeError: Cannot read property 'xxx' of undefined`
-
-**原因**：响应结构是 `{ data: { data: {...} } }`
-
-**错误代码**：
-```typescript
-const response = await api.get<ApiResponse<Entity>>('/entity/1')
-return response.data  // 这是外层 data
-```
-
-**正确代码**：
-```typescript
-const { data } = await api.get<ApiResponse<Entity>>('/entity/1')
-return data.data  // 这是内层 data
-```
-
----
-
-### G11: Table columns 类型错误
-
-**症状**：TypeScript 报类型不兼容
-
-**原因**：未使用 `ColumnsType<T>`
-
-**错误代码**：
-```tsx
-const columns = [
-    { title: 'Name', dataIndex: 'name' }
-]
-```
-
-**正确代码**：
-```tsx
-import type { ColumnsType } from 'antd/es/table'
-
-const columns: ColumnsType<Entity> = [
-    { title: 'Name', dataIndex: 'name', key: 'name' }
-]
-```
-
----
-
-### G12: Form 验证不触发
-
-**症状**：点击提交按钮无反应
-
-**原因**：未正确使用 `Form.useForm()` 或 `validateFields()`
-
-**错误代码**：
-```tsx
-const handleSubmit = () => {
-    const values = form.getFieldsValue()  // 不会触发验证
-}
-```
-
-**正确代码**：
-```tsx
-const handleSubmit = async () => {
-    try {
-        const values = await form.validateFields()  // 会触发验证
-        // 处理提交
-    } catch {
-        return  // 验证失败，不提交
-    }
-}
-```
-
----
-
-### G13: useCallback 依赖缺失
-
-**症状**：函数行为不符合预期，使用旧闭包值
-
-**原因**：useCallback 依赖数组不完整
-
-**错误代码**：
-```tsx
-const fetchData = useCallback(async () => {
-    const data = await listItems({ status: filter })  // filter 可能是旧值
-}, [])  // 缺少 filter 依赖
-```
-
-**正确代码**：
-```tsx
-const fetchData = useCallback(async () => {
-    const data = await listItems({ status: filter })
-}, [filter])  // 添加 filter 依赖
-```
-
----
-
-### G14: 权限菜单不显示
-
-**症状**：有权限但菜单不出现
-
-**原因**：
-1. `app.config.ts` 未启用模块
-2. 权限码不匹配
-
-**检查**：
-```typescript
-// routes.tsx
-handle: {
-    menu: {
-        permission: 'module:entity:view',  // 确保格式正确
-    }
-}
-
-// 后端权限注册
-reg.CreateActionI18n(
-    "module:entity:view",  // 必须与前端一致
-    ...
-)
-```
-
----
-
-## 性能陷阱
-
-### G15: N+1 查询
-
-**症状**：列表页加载慢，日志显示大量 SQL
-
-**原因**：循环中查询关联数据
-
-**错误代码**：
-```go
-entities, _ := repo.List(ctx, tenantID)
-for i := range entities {
-    entities[i].Category, _ = repo.GetCategory(entities[i].CategoryID)  // N次查询
-}
-```
-
-**正确代码**：
-```go
-// 使用 Preload
-r.db.Preload("Category").Find(&entities)
-
-// 或批量查询
-categoryIDs := extractIDs(entities)
-categories, _ := repo.GetCategoriesByIDs(categoryIDs)
-```
-
----
-
-### G16: 无限重渲染
-
-**症状**：页面卡死，控制台显示大量渲染日志
-
-**原因**：useEffect 依赖数组包含每次渲染都变化的值
-
-**错误代码**：
-```tsx
-useEffect(() => {
-    fetchData()
-}, [{ page, pageSize }])  // 对象每次都是新引用
-```
-
-**正确代码**：
-```tsx
-useEffect(() => {
-    fetchData()
-}, [page, pageSize])  // 使用原始值
-```
-
----
-
-## 快速排查表
-
-| 现象 | 首先检查 |
-|------|----------|
-| 404 Not Found | config.yaml + manifest.go 注册 |
-| 菜单不显示 | app.config.ts 启用 |
-| 翻译键原样显示 | RegisterI18n() + JSON 文件路径 |
-| nil pointer panic | Handler nil 检查 |
-| 数据泄露 | 租户 ID 过滤 |
-| TypeScript 报错 | 类型定义 + ColumnsType |
-| 表单验证无效 | validateFields() 使用 |
-| Modal 数据残留 | destroyOnHidden |