@robsun/create-keystone-app 0.2.11 → 0.2.13

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

@@ -1,532 +1,532 @@
-# Keystone 代码模板
-
-## 前端模板
-
-### Ant Design v6 注意事项
-- `Space` 使用 `orientation`，不要用 `direction`。
-- `Modal` 使用 `destroyOnHidden`，不要用 `destroyOnClose`。
-- `Drawer` 使用 `size`，不要用 `width`。
-
-### routes.tsx
-```tsx
-import { RouteObject } from 'react-router-dom'
-import { registerModule } from '@robsun/keystone-web-core'
-
-const routes: RouteObject[] = [
-  {
-    path: '{name}',
-    handle: {
-      menu: { title: '{Title}', icon: 'icon-name' },
-      permission: '{name}:{resource}:view',
-      helpKey: '{name}/index',
-    },
-    children: [
-      { index: true, lazy: () => import('./pages/List') },
-      { path: 'create', lazy: () => import('./pages/Form') },
-      { path: ':id', lazy: () => import('./pages/Detail') },
-      { path: ':id/edit', lazy: () => import('./pages/Form') },
-    ],
-  },
-]
-
-registerModule({ name: '{name}', routes })
-```
-
-### List.tsx (ProTable)
-```tsx
-import { useEffect, useState } from 'react'
-import { ProTable } from '@robsun/keystone-web-core'
-import type { PaginatedData } from '@robsun/keystone-web-core'
-import type { {Entity} } from '../types'
-import { list{Entity} } from '../services/api'
-
-const INITIAL_DATA: PaginatedData<{Entity}> = {
-  items: [],
-  total: 0,
-  page: 1,
-  page_size: 10,
-}
-
-export function Component() {
-  const [loading, setLoading] = useState(false)
-  const [data, setData] = useState(INITIAL_DATA)
-
-  const columns = [
-    { title: 'ID', dataIndex: 'id' },
-    { title: '名称', dataIndex: 'name' },
-  ]
-
-  const fetchData = async (page = data.page, pageSize = data.page_size) => {
-    setLoading(true)
-    try {
-      const result = await list{Entity}({ page, page_size: pageSize })
-      setData(result)
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  useEffect(() => {
-    void fetchData()
-  }, [])
-
-  return (
-    <ProTable
-      columns={columns}
-      dataSource={data.items}
-      rowKey="id"
-      loading={loading}
-      pagination={{
-        current: data.page,
-        pageSize: data.page_size,
-        total: data.total,
-        onChange: (page, pageSize) => {
-          void fetchData(page, pageSize)
-        },
-      }}
-    />
-  )
-}
-```
-
-### Form.tsx (ProForm)
-```tsx
-import { ProForm } from '@robsun/keystone-web-core'
-import { useParams, useNavigate } from 'react-router-dom'
-import { create{Entity}, update{Entity} } from '../services/api'
-
-export function Component() {
-  const { id: rawId } = useParams()
-  const navigate = useNavigate()
-  const id = Number(rawId)
-  const isEdit = Number.isFinite(id)
-
-  const onSubmit = async (values: any) => {
-    if (isEdit) {
-      await update{Entity}(id, values)
-    } else {
-      await create{Entity}(values)
-    }
-    navigate('/{name}')
-  }
-
-  return (
-    <ProForm onFinish={onSubmit}>
-      {/* 表单字段 */}
-    </ProForm>
-  )
-}
-```
-
-### services/api.ts
-```typescript
-import { api, type ApiResponse, type PaginatedData, type PaginationParams } from '@robsun/keystone-web-core'
-import type { {Entity} } from '../types'
-
-// 注意：使用 api 而非 apiClient，响应格式为 { data: { ... } }
-export const list{Entity} = async (params: PaginationParams = {}) => {
-  const { data } = await api.get<ApiResponse<PaginatedData<{Entity}>>>(
-    '/{module}/{resources}',
-    { params }
-  )
-  return data.data
-}
-
-export const create{Entity} = async (payload: Partial<{Entity}>) => {
-  const { data } = await api.post<ApiResponse<{Entity}>>('/{module}/{resources}', payload)
-  return data.data
-}
-
-export const update{Entity} = async (id: number, payload: Partial<{Entity}>) => {
-  const { data } = await api.patch<ApiResponse<{Entity}>>(`/{module}/{resources}/${id}`, payload)
-  return data.data
-}
-
-export const delete{Entity} = async (id: number) => {
-  await api.delete<ApiResponse<{ id: number }>>(`/{module}/{resources}/${id}`)
-}
-```
-
-### types.ts
-```typescript
-export interface {Entity} {
-  id: string
-  name: string
-  createdAt: string
-  updatedAt: string
-}
-```
-
-### i18n 翻译文件
-
-**locales/zh-CN/{module}.json**
-```json
-{
-  "title": "{模块标题}",
-  "list": {
-    "title": "{实体}列表",
-    "empty": "暂无数据",
-    "columns": {
-      "name": "名称",
-      "status": "状态",
-      "createdAt": "创建时间"
-    }
-  },
-  "form": {
-    "create": "创建{实体}",
-    "edit": "编辑{实体}",
-    "fields": {
-      "name": "名称",
-      "description": "描述"
-    },
-    "placeholders": {
-      "name": "请输入名称"
-    }
-  },
-  "actions": {
-    "create": "新建",
-    "edit": "编辑",
-    "delete": "删除",
-    "save": "保存",
-    "cancel": "取消"
-  },
-  "messages": {
-    "createSuccess": "创建成功",
-    "updateSuccess": "更新成功",
-    "deleteSuccess": "删除成功",
-    "deleteConfirm": "确定要删除吗？"
-  }
-}
-```
-
-**locales/en-US/{module}.json**
-```json
-{
-  "title": "{Module Title}",
-  "list": {
-    "title": "{Entity} List",
-    "empty": "No data",
-    "columns": {
-      "name": "Name",
-      "status": "Status",
-      "createdAt": "Created At"
-    }
-  },
-  "form": {
-    "create": "Create {Entity}",
-    "edit": "Edit {Entity}",
-    "fields": {
-      "name": "Name",
-      "description": "Description"
-    },
-    "placeholders": {
-      "name": "Enter name"
-    }
-  },
-  "actions": {
-    "create": "Create",
-    "edit": "Edit",
-    "delete": "Delete",
-    "save": "Save",
-    "cancel": "Cancel"
-  },
-  "messages": {
-    "createSuccess": "Created successfully",
-    "updateSuccess": "Updated successfully",
-    "deleteSuccess": "Deleted successfully",
-    "deleteConfirm": "Are you sure to delete?"
-  }
-}
-```
-
-### 使用翻译的 List.tsx
-```tsx
-import { useTranslation } from 'react-i18next'
-import { ProTable } from '@robsun/keystone-web-core'
-
-export function Component() {
-  const { t } = useTranslation()  // 自动使用当前模块的命名空间
-
-  const columns = [
-    { title: t('{module}:list.columns.name'), dataIndex: 'name' },
-    { title: t('{module}:list.columns.status'), dataIndex: 'status' },
-    { title: t('{module}:list.columns.createdAt'), dataIndex: 'createdAt' },
-  ]
-
-  return (
-    <ProTable
-      columns={columns}
-      // ...
-    />
-  )
-}
-```
-
-## 后端模板
-
-### module.go
-```go
-package {name}
-
-import (
-    "github.com/gin-gonic/gin"
-    "gorm.io/gorm"
-)
-
-type Module struct{}
-
-func (m *Module) Name() string { return "{name}" }
-
-func (m *Module) RegisterRoutes(r *gin.RouterGroup) {
-    g := r.Group("/{name}")
-    g.GET("", handler.List)
-    g.GET("/:id", handler.Detail)
-    g.POST("", handler.Create)
-    g.PATCH("/:id", handler.Update)
-    g.DELETE("/:id", handler.Delete)
-}
-
-func (m *Module) RegisterPermissions() []Permission {
-    return []Permission{
-        {Name: "{name}:{resource}:view", Title: "查看{Title}"},
-        {Name: "{name}:{resource}:create", Title: "创建{Title}"},
-        {Name: "{name}:{resource}:update", Title: "编辑{Title}"},
-        {Name: "{name}:{resource}:delete", Title: "删除{Title}"},
-    }
-}
-
-func (m *Module) Migrate(db *gorm.DB) error {
-    return db.AutoMigrate(&models.{Entity}{})
-}
-
-func (m *Module) Seed(db *gorm.DB) error { return nil }
-```
-
-### handler/list.go
-```go
-package handler
-
-import (
-    "github.com/gin-gonic/gin"
-)
-
-func (h *Handler) List(c *gin.Context) {
-    page, pageSize := parsePagination(c)
-    items, total, err := h.svc.List(c, page, pageSize)
-    if err != nil {
-        respondError(c, err)
-        return
-    }
-    respondPaginated(c, items, total, page, pageSize)
-}
-```
-
-### domain/models/entity.go
-```go
-package models
-
-import "time"
-
-type {Entity} struct {
-    ID        string    `json:"id" gorm:"primaryKey"`
-    Name      string    `json:"name"`
-    CreatedAt time.Time `json:"createdAt"`
-    UpdatedAt time.Time `json:"updatedAt"`
-}
-```
-
-### domain/service/service.go
-```go
-package service
-
-type Service struct {
-    repo *repository.Repository
-}
-
-func NewService(repo *repository.Repository) *Service {
-    return &Service{repo: repo}
-}
-
-func (s *Service) List(ctx context.Context, page, pageSize int) ([]models.{Entity}, int64, error) {
-    return s.repo.List(ctx, page, pageSize)
-}
-
-func (s *Service) Get(ctx context.Context, id string) (*models.{Entity}, error) {
-    return s.repo.Get(ctx, id)
-}
-
-func (s *Service) Create(ctx context.Context, entity *models.{Entity}) error {
-    return s.repo.Create(ctx, entity)
-}
-
-func (s *Service) Update(ctx context.Context, id string, entity *models.{Entity}) error {
-    return s.repo.Update(ctx, id, entity)
-}
-
-func (s *Service) Delete(ctx context.Context, id string) error {
-    return s.repo.Delete(ctx, id)
-}
-```
-
-### infra/repository/repo.go
-```go
-package repository
-
-import (
-    "context"
-    "gorm.io/gorm"
-)
-
-type Repository struct {
-    db *gorm.DB
-}
-
-func NewRepository(db *gorm.DB) *Repository {
-    return &Repository{db: db}
-}
-
-func (r *Repository) List(ctx context.Context, page, pageSize int) ([]models.{Entity}, int64, error) {
-    var items []models.{Entity}
-    var total int64
-
-    r.db.Model(&models.{Entity}{}).Count(&total)
-    r.db.Offset((page - 1) * pageSize).Limit(pageSize).Find(&items)
-
-    return items, total, nil
-}
-
-func (r *Repository) Get(ctx context.Context, id string) (*models.{Entity}, error) {
-    var item models.{Entity}
-    if err := r.db.First(&item, "id = ?", id).Error; err != nil {
-        return nil, err
-    }
-    return &item, nil
-}
-
-func (r *Repository) Create(ctx context.Context, entity *models.{Entity}) error {
-    return r.db.Create(entity).Error
-}
-
-func (r *Repository) Update(ctx context.Context, id string, entity *models.{Entity}) error {
-    return r.db.Model(&models.{Entity}{}).Where("id = ?", id).Updates(entity).Error
-}
-
-func (r *Repository) Delete(ctx context.Context, id string) error {
-    return r.db.Delete(&models.{Entity}{}, "id = ?", id).Error
-}
-```
-
-### i18n/i18n.go
-```go
-package i18n
-
-import (
-    "embed"
-    "github.com/robsuncn/keystone/infra/i18n"
-)
-
-//go:embed locales/*.json
-var Translations embed.FS
-
-func init() {
-    // 注册模块翻译文件
-    i18n.MustLoadModuleTranslations("{module}", Translations)
-}
-```
-
-### i18n/keys.go
-```go
-package i18n
-
-// 翻译键常量定义
-const (
-    // 成功消息
-    KeyItemCreated = "{module}.item.created"
-    KeyItemUpdated = "{module}.item.updated"
-    KeyItemDeleted = "{module}.item.deleted"
-
-    // 错误消息
-    KeyItemNotFound     = "{module}.item.notFound"
-    KeyItemInvalid      = "{module}.item.invalid"
-    KeyItemAlreadyExists = "{module}.item.alreadyExists"
-
-    // 验证消息
-    KeyNameRequired = "{module}.validation.nameRequired"
-    KeyNameTooLong  = "{module}.validation.nameTooLong"
-)
-```
-
-### i18n/locales/zh-CN.json
-```json
-{
-  "{module}": {
-    "item": {
-      "created": "{实体}创建成功",
-      "updated": "{实体}更新成功",
-      "deleted": "{实体}删除成功",
-      "notFound": "{实体}不存在",
-      "invalid": "{实体}数据无效",
-      "alreadyExists": "{实体}已存在"
-    },
-    "validation": {
-      "nameRequired": "名称不能为空",
-      "nameTooLong": "名称长度不能超过 {{max}} 个字符"
-    }
-  }
-}
-```
-
-### i18n/locales/en-US.json
-```json
-{
-  "{module}": {
-    "item": {
-      "created": "{Entity} created successfully",
-      "updated": "{Entity} updated successfully",
-      "deleted": "{Entity} deleted successfully",
-      "notFound": "{Entity} not found",
-      "invalid": "Invalid {entity} data",
-      "alreadyExists": "{Entity} already exists"
-    },
-    "validation": {
-      "nameRequired": "Name is required",
-      "nameTooLong": "Name cannot exceed {{max}} characters"
-    }
-  }
-}
-```
-
-### 使用翻译的 service.go
-```go
-package service
-
-import (
-    "errors"
-    "github.com/gin-gonic/gin"
-    "github.com/robsuncn/keystone/infra/i18n"
-    modulei18n "app/internal/modules/{module}/i18n"
-)
-
-func (s *Service) Get(c *gin.Context, id string) (*models.{Entity}, error) {
-    item, err := s.repo.Get(c, id)
-    if err != nil {
-        // 使用翻译键返回错误
-        return nil, errors.New(i18n.T(c, modulei18n.KeyItemNotFound))
-    }
-    return item, nil
-}
-
-func (s *Service) Create(c *gin.Context, entity *models.{Entity}) error {
-    if entity.Name == "" {
-        return errors.New(i18n.T(c, modulei18n.KeyNameRequired))
-    }
-
-    err := s.repo.Create(c, entity)
-    if err != nil {
-        return err
-    }
-
-    // 可以在日志或审计中使用翻译消息
-    return nil
-}
-```
+# Keystone 代码模板
+
+## 前端模板
+
+### Ant Design v6 注意事项
+- `Space` 使用 `orientation`，不要用 `direction`。
+- `Modal` 使用 `destroyOnHidden`，不要用 `destroyOnClose`。
+- `Drawer` 使用 `size`，不要用 `width`。
+
+### routes.tsx
+```tsx
+import { RouteObject } from 'react-router-dom'
+import { registerModule } from '@robsun/keystone-web-core'
+
+const routes: RouteObject[] = [
+  {
+    path: '{name}',
+    handle: {
+      menu: { title: '{Title}', icon: 'icon-name' },
+      permission: '{name}:{resource}:view',
+      helpKey: '{name}/index',
+    },
+    children: [
+      { index: true, lazy: () => import('./pages/List') },
+      { path: 'create', lazy: () => import('./pages/Form') },
+      { path: ':id', lazy: () => import('./pages/Detail') },
+      { path: ':id/edit', lazy: () => import('./pages/Form') },
+    ],
+  },
+]
+
+registerModule({ name: '{name}', routes })
+```
+
+### List.tsx (ProTable)
+```tsx
+import { useEffect, useState } from 'react'
+import { ProTable } from '@robsun/keystone-web-core'
+import type { PaginatedData } from '@robsun/keystone-web-core'
+import type { {Entity} } from '../types'
+import { list{Entity} } from '../services/api'
+
+const INITIAL_DATA: PaginatedData<{Entity}> = {
+  items: [],
+  total: 0,
+  page: 1,
+  page_size: 10,
+}
+
+export function Component() {
+  const [loading, setLoading] = useState(false)
+  const [data, setData] = useState(INITIAL_DATA)
+
+  const columns = [
+    { title: 'ID', dataIndex: 'id' },
+    { title: '名称', dataIndex: 'name' },
+  ]
+
+  const fetchData = async (page = data.page, pageSize = data.page_size) => {
+    setLoading(true)
+    try {
+      const result = await list{Entity}({ page, page_size: pageSize })
+      setData(result)
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    void fetchData()
+  }, [])
+
+  return (
+    <ProTable
+      columns={columns}
+      dataSource={data.items}
+      rowKey="id"
+      loading={loading}
+      pagination={{
+        current: data.page,
+        pageSize: data.page_size,
+        total: data.total,
+        onChange: (page, pageSize) => {
+          void fetchData(page, pageSize)
+        },
+      }}
+    />
+  )
+}
+```
+
+### Form.tsx (ProForm)
+```tsx
+import { ProForm } from '@robsun/keystone-web-core'
+import { useParams, useNavigate } from 'react-router-dom'
+import { create{Entity}, update{Entity} } from '../services/api'
+
+export function Component() {
+  const { id: rawId } = useParams()
+  const navigate = useNavigate()
+  const id = Number(rawId)
+  const isEdit = Number.isFinite(id)
+
+  const onSubmit = async (values: any) => {
+    if (isEdit) {
+      await update{Entity}(id, values)
+    } else {
+      await create{Entity}(values)
+    }
+    navigate('/{name}')
+  }
+
+  return (
+    <ProForm onFinish={onSubmit}>
+      {/* 表单字段 */}
+    </ProForm>
+  )
+}
+```
+
+### services/api.ts
+```typescript
+import { api, type ApiResponse, type PaginatedData, type PaginationParams } from '@robsun/keystone-web-core'
+import type { {Entity} } from '../types'
+
+// 注意：使用 api 而非 apiClient，响应格式为 { data: { ... } }
+export const list{Entity} = async (params: PaginationParams = {}) => {
+  const { data } = await api.get<ApiResponse<PaginatedData<{Entity}>>>(
+    '/{module}/{resources}',
+    { params }
+  )
+  return data.data
+}
+
+export const create{Entity} = async (payload: Partial<{Entity}>) => {
+  const { data } = await api.post<ApiResponse<{Entity}>>('/{module}/{resources}', payload)
+  return data.data
+}
+
+export const update{Entity} = async (id: number, payload: Partial<{Entity}>) => {
+  const { data } = await api.patch<ApiResponse<{Entity}>>(`/{module}/{resources}/${id}`, payload)
+  return data.data
+}
+
+export const delete{Entity} = async (id: number) => {
+  await api.delete<ApiResponse<{ id: number }>>(`/{module}/{resources}/${id}`)
+}
+```
+
+### types.ts
+```typescript
+export interface {Entity} {
+  id: string
+  name: string
+  createdAt: string
+  updatedAt: string
+}
+```
+
+### i18n 翻译文件
+
+**locales/zh-CN/{module}.json**
+```json
+{
+  "title": "{模块标题}",
+  "list": {
+    "title": "{实体}列表",
+    "empty": "暂无数据",
+    "columns": {
+      "name": "名称",
+      "status": "状态",
+      "createdAt": "创建时间"
+    }
+  },
+  "form": {
+    "create": "创建{实体}",
+    "edit": "编辑{实体}",
+    "fields": {
+      "name": "名称",
+      "description": "描述"
+    },
+    "placeholders": {
+      "name": "请输入名称"
+    }
+  },
+  "actions": {
+    "create": "新建",
+    "edit": "编辑",
+    "delete": "删除",
+    "save": "保存",
+    "cancel": "取消"
+  },
+  "messages": {
+    "createSuccess": "创建成功",
+    "updateSuccess": "更新成功",
+    "deleteSuccess": "删除成功",
+    "deleteConfirm": "确定要删除吗？"
+  }
+}
+```
+
+**locales/en-US/{module}.json**
+```json
+{
+  "title": "{Module Title}",
+  "list": {
+    "title": "{Entity} List",
+    "empty": "No data",
+    "columns": {
+      "name": "Name",
+      "status": "Status",
+      "createdAt": "Created At"
+    }
+  },
+  "form": {
+    "create": "Create {Entity}",
+    "edit": "Edit {Entity}",
+    "fields": {
+      "name": "Name",
+      "description": "Description"
+    },
+    "placeholders": {
+      "name": "Enter name"
+    }
+  },
+  "actions": {
+    "create": "Create",
+    "edit": "Edit",
+    "delete": "Delete",
+    "save": "Save",
+    "cancel": "Cancel"
+  },
+  "messages": {
+    "createSuccess": "Created successfully",
+    "updateSuccess": "Updated successfully",
+    "deleteSuccess": "Deleted successfully",
+    "deleteConfirm": "Are you sure to delete?"
+  }
+}
+```
+
+### 使用翻译的 List.tsx
+```tsx
+import { useTranslation } from 'react-i18next'
+import { ProTable } from '@robsun/keystone-web-core'
+
+export function Component() {
+  const { t } = useTranslation()  // 自动使用当前模块的命名空间
+
+  const columns = [
+    { title: t('{module}:list.columns.name'), dataIndex: 'name' },
+    { title: t('{module}:list.columns.status'), dataIndex: 'status' },
+    { title: t('{module}:list.columns.createdAt'), dataIndex: 'createdAt' },
+  ]
+
+  return (
+    <ProTable
+      columns={columns}
+      // ...
+    />
+  )
+}
+```
+
+## 后端模板
+
+### module.go
+```go
+package {name}
+
+import (
+    "github.com/gin-gonic/gin"
+    "gorm.io/gorm"
+)
+
+type Module struct{}
+
+func (m *Module) Name() string { return "{name}" }
+
+func (m *Module) RegisterRoutes(r *gin.RouterGroup) {
+    g := r.Group("/{name}")
+    g.GET("", handler.List)
+    g.GET("/:id", handler.Detail)
+    g.POST("", handler.Create)
+    g.PATCH("/:id", handler.Update)
+    g.DELETE("/:id", handler.Delete)
+}
+
+func (m *Module) RegisterPermissions() []Permission {
+    return []Permission{
+        {Name: "{name}:{resource}:view", Title: "查看{Title}"},
+        {Name: "{name}:{resource}:create", Title: "创建{Title}"},
+        {Name: "{name}:{resource}:update", Title: "编辑{Title}"},
+        {Name: "{name}:{resource}:delete", Title: "删除{Title}"},
+    }
+}
+
+func (m *Module) Migrate(db *gorm.DB) error {
+    return db.AutoMigrate(&models.{Entity}{})
+}
+
+func (m *Module) Seed(db *gorm.DB) error { return nil }
+```
+
+### handler/list.go
+```go
+package handler
+
+import (
+    "github.com/gin-gonic/gin"
+)
+
+func (h *Handler) List(c *gin.Context) {
+    page, pageSize := parsePagination(c)
+    items, total, err := h.svc.List(c, page, pageSize)
+    if err != nil {
+        respondError(c, err)
+        return
+    }
+    respondPaginated(c, items, total, page, pageSize)
+}
+```
+
+### domain/models/entity.go
+```go
+package models
+
+import "time"
+
+type {Entity} struct {
+    ID        string    `json:"id" gorm:"primaryKey"`
+    Name      string    `json:"name"`
+    CreatedAt time.Time `json:"createdAt"`
+    UpdatedAt time.Time `json:"updatedAt"`
+}
+```
+
+### domain/service/service.go
+```go
+package service
+
+type Service struct {
+    repo *repository.Repository
+}
+
+func NewService(repo *repository.Repository) *Service {
+    return &Service{repo: repo}
+}
+
+func (s *Service) List(ctx context.Context, page, pageSize int) ([]models.{Entity}, int64, error) {
+    return s.repo.List(ctx, page, pageSize)
+}
+
+func (s *Service) Get(ctx context.Context, id string) (*models.{Entity}, error) {
+    return s.repo.Get(ctx, id)
+}
+
+func (s *Service) Create(ctx context.Context, entity *models.{Entity}) error {
+    return s.repo.Create(ctx, entity)
+}
+
+func (s *Service) Update(ctx context.Context, id string, entity *models.{Entity}) error {
+    return s.repo.Update(ctx, id, entity)
+}
+
+func (s *Service) Delete(ctx context.Context, id string) error {
+    return s.repo.Delete(ctx, id)
+}
+```
+
+### infra/repository/repo.go
+```go
+package repository
+
+import (
+    "context"
+    "gorm.io/gorm"
+)
+
+type Repository struct {
+    db *gorm.DB
+}
+
+func NewRepository(db *gorm.DB) *Repository {
+    return &Repository{db: db}
+}
+
+func (r *Repository) List(ctx context.Context, page, pageSize int) ([]models.{Entity}, int64, error) {
+    var items []models.{Entity}
+    var total int64
+
+    r.db.Model(&models.{Entity}{}).Count(&total)
+    r.db.Offset((page - 1) * pageSize).Limit(pageSize).Find(&items)
+
+    return items, total, nil
+}
+
+func (r *Repository) Get(ctx context.Context, id string) (*models.{Entity}, error) {
+    var item models.{Entity}
+    if err := r.db.First(&item, "id = ?", id).Error; err != nil {
+        return nil, err
+    }
+    return &item, nil
+}
+
+func (r *Repository) Create(ctx context.Context, entity *models.{Entity}) error {
+    return r.db.Create(entity).Error
+}
+
+func (r *Repository) Update(ctx context.Context, id string, entity *models.{Entity}) error {
+    return r.db.Model(&models.{Entity}{}).Where("id = ?", id).Updates(entity).Error
+}
+
+func (r *Repository) Delete(ctx context.Context, id string) error {
+    return r.db.Delete(&models.{Entity}{}, "id = ?", id).Error
+}
+```
+
+### i18n/i18n.go
+```go
+package i18n
+
+import (
+    "embed"
+    "github.com/robsuncn/keystone/infra/i18n"
+)
+
+//go:embed locales/*.json
+var Translations embed.FS
+
+func init() {
+    // 注册模块翻译文件
+    i18n.MustLoadModuleTranslations("{module}", Translations)
+}
+```
+
+### i18n/keys.go
+```go
+package i18n
+
+// 翻译键常量定义
+const (
+    // 成功消息
+    KeyItemCreated = "{module}.item.created"
+    KeyItemUpdated = "{module}.item.updated"
+    KeyItemDeleted = "{module}.item.deleted"
+
+    // 错误消息
+    KeyItemNotFound     = "{module}.item.notFound"
+    KeyItemInvalid      = "{module}.item.invalid"
+    KeyItemAlreadyExists = "{module}.item.alreadyExists"
+
+    // 验证消息
+    KeyNameRequired = "{module}.validation.nameRequired"
+    KeyNameTooLong  = "{module}.validation.nameTooLong"
+)
+```
+
+### i18n/locales/zh-CN.json
+```json
+{
+  "{module}": {
+    "item": {
+      "created": "{实体}创建成功",
+      "updated": "{实体}更新成功",
+      "deleted": "{实体}删除成功",
+      "notFound": "{实体}不存在",
+      "invalid": "{实体}数据无效",
+      "alreadyExists": "{实体}已存在"
+    },
+    "validation": {
+      "nameRequired": "名称不能为空",
+      "nameTooLong": "名称长度不能超过 {{max}} 个字符"
+    }
+  }
+}
+```
+
+### i18n/locales/en-US.json
+```json
+{
+  "{module}": {
+    "item": {
+      "created": "{Entity} created successfully",
+      "updated": "{Entity} updated successfully",
+      "deleted": "{Entity} deleted successfully",
+      "notFound": "{Entity} not found",
+      "invalid": "Invalid {entity} data",
+      "alreadyExists": "{Entity} already exists"
+    },
+    "validation": {
+      "nameRequired": "Name is required",
+      "nameTooLong": "Name cannot exceed {{max}} characters"
+    }
+  }
+}
+```
+
+### 使用翻译的 service.go
+```go
+package service
+
+import (
+    "errors"
+    "github.com/gin-gonic/gin"
+    "github.com/robsuncn/keystone/infra/i18n"
+    modulei18n "app/internal/modules/{module}/i18n"
+)
+
+func (s *Service) Get(c *gin.Context, id string) (*models.{Entity}, error) {
+    item, err := s.repo.Get(c, id)
+    if err != nil {
+        // 使用翻译键返回错误
+        return nil, errors.New(i18n.T(c, modulei18n.KeyItemNotFound))
+    }
+    return item, nil
+}
+
+func (s *Service) Create(c *gin.Context, entity *models.{Entity}) error {
+    if entity.Name == "" {
+        return errors.New(i18n.T(c, modulei18n.KeyNameRequired))
+    }
+
+    err := s.repo.Create(c, entity)
+    if err != nil {
+        return err
+    }
+
+    // 可以在日志或审计中使用翻译消息
+    return nil
+}
+```