@robsun/create-keystone-app 0.2.12 → 0.2.15

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

@@ -1,532 +1,2710 @@
 # Keystone 代码模板
 
-## 前端模板
+> 所有模板基于 example 模块实际代码，使用占位符标记变量部分。
+> 复制后替换占位符即可运行。
 
-### 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'
+| 占位符 | 含义 | 示例 |
+|--------|------|------|
+| `__MODULE__` | 模块名 (小写) | `order`, `product` |
+| `__MODULE_TITLE__` | 模块中文名 | `订单`, `商品` |
+| `__ENTITY__` | 实体名 (PascalCase) | `Order`, `Product` |
+| `__ENTITY_LOWER__` | 实体名 (小写) | `order`, `product` |
+| `__RESOURCE__` | 资源名 (复数小写) | `orders`, `products` |
+| `__APP_NAME__` | 应用名 (go.mod 中定义) | 脚手架自动替换 |
 
-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'
+### 1. module.go (模块入口)
 
-const INITIAL_DATA: PaginatedData<{Entity}> = {
-  items: [],
-  total: 0,
-  page: 1,
-  page_size: 10,
-}
+```go
+package __MODULE__
 
-export function Component() {
-  const [loading, setLoading] = useState(false)
-  const [data, setData] = useState(INITIAL_DATA)
+import (
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/robsuncn/keystone/domain/permissions"
+	"github.com/robsuncn/keystone/infra/jobs"
+
+	handler "__APP_NAME__/apps/server/internal/modules/__MODULE__/api/handler"
+	migrations "__APP_NAME__/apps/server/internal/modules/__MODULE__/bootstrap/migrations"
+	seeds "__APP_NAME__/apps/server/internal/modules/__MODULE__/bootstrap/seeds"
+	models "__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
+	service "__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/service"
+	modulei18n "__APP_NAME__/apps/server/internal/modules/__MODULE__/i18n"
+	repository "__APP_NAME__/apps/server/internal/modules/__MODULE__/infra/repository"
+)
 
-  const columns = [
-    { title: 'ID', dataIndex: 'id' },
-    { title: '名称', dataIndex: 'name' },
-  ]
+type Module struct {
+	svc *service.__ENTITY__Service
+}
 
-  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)
-    }
-  }
+func NewModule() *Module {
+	return &Module{}
+}
 
-  useEffect(() => {
-    void fetchData()
-  }, [])
+func (m *Module) Name() string {
+	return "__MODULE__"
+}
 
-  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)
-        },
-      }}
-    />
-  )
+func (m *Module) RegisterRoutes(rg *gin.RouterGroup) {
+	if rg == nil || m == nil {
+		return
+	}
+	h := handler.New__ENTITY__Handler(m.svc)
+	if h == nil {
+		return
+	}
+	group := rg.Group("/__MODULE__")
+	group.GET("/__RESOURCE__", h.List)
+	group.POST("/__RESOURCE__", h.Create)
+	group.GET("/__RESOURCE__/:id", h.Get)
+	group.PATCH("/__RESOURCE__/:id", h.Update)
+	group.DELETE("/__RESOURCE__/:id", h.Delete)
 }
-```
 
-### 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}')
-  }
+func (m *Module) RegisterModels() []interface{} {
+	return []interface{}{&models.__ENTITY__{}}
+}
 
-  return (
-    <ProForm onFinish={onSubmit}>
-      {/* 表单字段 */}
-    </ProForm>
-  )
+func (m *Module) RegisterPermissions(reg *permissions.Registry) error {
+	if reg == nil {
+		return nil
+	}
+	// 菜单权限
+	if err := reg.CreateMenuI18n(
+		"__MODULE__:__ENTITY_LOWER__",
+		"__MODULE_TITLE__",
+		"permission.__MODULE__.__ENTITY_LOWER__",
+		"__MODULE__",
+		10,
+	); err != nil {
+		return err
+	}
+	// 操作权限
+	if err := reg.CreateActionI18n(
+		"__MODULE__:__ENTITY_LOWER__:view",
+		"View __MODULE_TITLE__",
+		"permission.__MODULE__.__ENTITY_LOWER__.view",
+		"__MODULE__",
+		"__MODULE__:__ENTITY_LOWER__",
+	); err != nil {
+		return err
+	}
+	if err := reg.CreateActionI18n(
+		"__MODULE__:__ENTITY_LOWER__:manage",
+		"Manage __MODULE_TITLE__",
+		"permission.__MODULE__.__ENTITY_LOWER__.manage",
+		"__MODULE__",
+		"__MODULE__:__ENTITY_LOWER__",
+	); err != nil {
+		return err
+	}
+	return nil
 }
-```
 
-### 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
+func (m *Module) RegisterI18n() error {
+	return modulei18n.RegisterLocales()
 }
 
-export const create{Entity} = async (payload: Partial<{Entity}>) => {
-  const { data } = await api.post<ApiResponse<{Entity}>>('/{module}/{resources}', payload)
-  return data.data
+func (m *Module) RegisterJobs(_ *jobs.Registry) error {
+	return nil
 }
 
-export const update{Entity} = async (id: number, payload: Partial<{Entity}>) => {
-  const { data } = await api.patch<ApiResponse<{Entity}>>(`/{module}/{resources}/${id}`, payload)
-  return data.data
+func (m *Module) Migrate(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+	m.ensureServices(db)
+	return migrations.Migrate(db)
 }
 
-export const delete{Entity} = async (id: number) => {
-  await api.delete<ApiResponse<{ id: number }>>(`/{module}/{resources}/${id}`)
+func (m *Module) Seed(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+	m.ensureServices(db)
+	return seeds.Seed(db)
 }
-```
 
-### types.ts
-```typescript
-export interface {Entity} {
-  id: string
-  name: string
-  createdAt: string
-  updatedAt: string
+func (m *Module) ensureServices(db *gorm.DB) {
+	if m == nil || db == nil || m.svc != nil {
+		return
+	}
+	repo := repository.New__ENTITY__Repository(db)
+	m.svc = service.New__ENTITY__Service(repo)
 }
 ```
 
-### i18n 翻译文件
+### 2. domain/models/entity.go (模型)
 
-**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": "确定要删除吗？"
-  }
-}
-```
+```go
+package models
 
-**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?"
-  }
-}
-```
+import "github.com/robsuncn/keystone/domain/models"
 
-### 使用翻译的 List.tsx
-```tsx
-import { useTranslation } from 'react-i18next'
-import { ProTable } from '@robsun/keystone-web-core'
+type __ENTITY__Status string
 
-export function Component() {
-  const { t } = useTranslation()  // 自动使用当前模块的命名空间
+const (
+	Status__ENTITY__Active   __ENTITY__Status = "active"
+	Status__ENTITY__Inactive __ENTITY__Status = "inactive"
+)
 
-  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' },
-  ]
+func (s __ENTITY__Status) IsValid() bool {
+	switch s {
+	case Status__ENTITY__Active, Status__ENTITY__Inactive:
+		return true
+	default:
+		return false
+	}
+}
 
-  return (
-    <ProTable
-      columns={columns}
-      // ...
-    />
-  )
+type __ENTITY__ struct {
+	models.BaseModel
+	Name        string           `gorm:"size:200;not null" json:"name"`
+	Description string           `gorm:"size:1000" json:"description"`
+	Status      __ENTITY__Status `gorm:"size:20;not null;default:'active'" json:"status"`
+}
+
+func (__ENTITY__) TableName() string {
+	return "__MODULE_____RESOURCE__"
 }
 ```
 
-## 后端模板
+### 3. domain/service/service.go (服务层)
 
-### module.go
 ```go
-package {name}
+package service
 
 import (
-    "github.com/gin-gonic/gin"
-    "gorm.io/gorm"
+	"context"
+	"strings"
+
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
 )
 
-type Module struct{}
+type __ENTITY__Repository interface {
+	List(ctx context.Context, tenantID uint) ([]models.__ENTITY__, error)
+	FindByID(tenantID, id uint) (*models.__ENTITY__, error)
+	Create(ctx context.Context, entity *models.__ENTITY__) error
+	Update(ctx context.Context, entity *models.__ENTITY__) error
+	Delete(ctx context.Context, entity *models.__ENTITY__) error
+}
+
+type __ENTITY__Service struct {
+	repo __ENTITY__Repository
+}
 
-func (m *Module) Name() string { return "{name}" }
+type __ENTITY__Input struct {
+	Name        string
+	Description string
+	Status      models.__ENTITY__Status
+}
 
-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)
+type __ENTITY__UpdateInput struct {
+	Name        *string
+	Description *string
+	Status      *models.__ENTITY__Status
 }
 
-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 New__ENTITY__Service(repo __ENTITY__Repository) *__ENTITY__Service {
+	return &__ENTITY__Service{repo: repo}
 }
 
-func (m *Module) Migrate(db *gorm.DB) error {
-    return db.AutoMigrate(&models.{Entity}{})
+func (s *__ENTITY__Service) List(ctx context.Context, tenantID uint) ([]models.__ENTITY__, error) {
+	return s.repo.List(ctx, tenantID)
+}
+
+func (s *__ENTITY__Service) Create(ctx context.Context, tenantID uint, input __ENTITY__Input) (*models.__ENTITY__, error) {
+	name := strings.TrimSpace(input.Name)
+	if name == "" {
+		return nil, ErrNameRequired
+	}
+
+	status := input.Status
+	if status == "" {
+		status = models.Status__ENTITY__Active
+	}
+	if !status.IsValid() {
+		return nil, ErrStatusInvalid
+	}
+
+	entity := &models.__ENTITY__{
+		Name:        name,
+		Description: strings.TrimSpace(input.Description),
+		Status:      status,
+	}
+	entity.TenantID = tenantID
+
+	if err := s.repo.Create(ctx, entity); err != nil {
+		return nil, err
+	}
+	return entity, nil
+}
+
+func (s *__ENTITY__Service) Update(
+	ctx context.Context,
+	tenantID, id uint,
+	input __ENTITY__UpdateInput,
+) (*models.__ENTITY__, error) {
+	entity, err := s.repo.FindByID(tenantID, id)
+	if err != nil {
+		return nil, err
+	}
+
+	if input.Name != nil {
+		name := strings.TrimSpace(*input.Name)
+		if name == "" {
+			return nil, ErrNameRequired
+		}
+		entity.Name = name
+	}
+
+	if input.Description != nil {
+		entity.Description = strings.TrimSpace(*input.Description)
+	}
+
+	if input.Status != nil {
+		if !input.Status.IsValid() {
+			return nil, ErrStatusInvalid
+		}
+		entity.Status = *input.Status
+	}
+
+	if err := s.repo.Update(ctx, entity); err != nil {
+		return nil, err
+	}
+	return entity, nil
 }
 
-func (m *Module) Seed(db *gorm.DB) error { return nil }
+func (s *__ENTITY__Service) Delete(ctx context.Context, tenantID, id uint) error {
+	entity, err := s.repo.FindByID(tenantID, id)
+	if err != nil {
+		return err
+	}
+	return s.repo.Delete(ctx, entity)
+}
 ```
 
-### handler/list.go
+### 4. domain/service/errors.go (错误定义)
+
 ```go
-package handler
+package service
 
 import (
-    "github.com/gin-gonic/gin"
+	"github.com/robsuncn/keystone/infra/i18n"
+	modulei18n "__APP_NAME__/apps/server/internal/modules/__MODULE__/i18n"
 )
 
-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)
-}
+var (
+	Err__ENTITY__NotFound = &i18n.I18nError{Key: modulei18n.Msg__ENTITY__NotFound}
+	ErrNameRequired       = &i18n.I18nError{Key: modulei18n.MsgNameRequired}
+	ErrStatusInvalid      = &i18n.I18nError{Key: modulei18n.MsgStatusInvalid}
+)
 ```
 
-### domain/models/entity.go
+### 5. api/handler/handler.go (HTTP 处理器)
+
 ```go
-package models
+package handler
+
+import (
+	"errors"
 
-import "time"
+	"github.com/gin-gonic/gin"
+	hcommon "github.com/robsuncn/keystone/api/handler/common"
+	"github.com/robsuncn/keystone/api/response"
+	"github.com/robsuncn/keystone/infra/i18n"
 
-type {Entity} struct {
-    ID        string    `json:"id" gorm:"primaryKey"`
-    Name      string    `json:"name"`
-    CreatedAt time.Time `json:"createdAt"`
-    UpdatedAt time.Time `json:"updatedAt"`
+	modulei18n "__APP_NAME__/apps/server/internal/modules/__MODULE__/i18n"
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/service"
+)
+
+type __ENTITY__Handler struct {
+	svc *service.__ENTITY__Service
 }
-```
 
-### domain/service/service.go
-```go
-package service
+func New__ENTITY__Handler(svc *service.__ENTITY__Service) *__ENTITY__Handler {
+	if svc == nil {
+		return nil
+	}
+	return &__ENTITY__Handler{svc: svc}
+}
+
+type createInput struct {
+	Name        string               `json:"name"`
+	Description string               `json:"description"`
+	Status      models.__ENTITY__Status `json:"status"`
+}
 
-type Service struct {
-    repo *repository.Repository
+type updateInput struct {
+	Name        *string               `json:"name"`
+	Description *string               `json:"description"`
+	Status      *models.__ENTITY__Status `json:"status"`
 }
 
-func NewService(repo *repository.Repository) *Service {
-    return &Service{repo: repo}
+const defaultTenantID uint = 1
+
+func (h *__ENTITY__Handler) List(c *gin.Context) {
+	if h == nil || h.svc == nil {
+		response.ServiceUnavailableI18n(c, modulei18n.MsgServiceUnavailable)
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	items, err := h.svc.List(c.Request.Context(), tenantID)
+	if err != nil {
+		response.InternalErrorI18n(c, modulei18n.MsgLoadFailed)
+		return
+	}
+
+	response.Success(c, gin.H{"items": items})
 }
 
-func (s *Service) List(ctx context.Context, page, pageSize int) ([]models.{Entity}, int64, error) {
-    return s.repo.List(ctx, page, pageSize)
+func (h *__ENTITY__Handler) Get(c *gin.Context) {
+	if h == nil || h.svc == nil {
+		response.ServiceUnavailableI18n(c, modulei18n.MsgServiceUnavailable)
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	id, err := hcommon.ParseUintParam(c, "id")
+	if err != nil || id == 0 {
+		response.BadRequestI18n(c, modulei18n.MsgInvalidID)
+		return
+	}
+
+	// 需要在 service 中添加 Get 方法
+	// item, err := h.svc.Get(c.Request.Context(), tenantID, id)
+	// ...
+	response.Success(c, gin.H{"id": id, "tenant_id": tenantID})
 }
 
-func (s *Service) Get(ctx context.Context, id string) (*models.{Entity}, error) {
-    return s.repo.Get(ctx, id)
+func (h *__ENTITY__Handler) Create(c *gin.Context) {
+	if h == nil || h.svc == nil {
+		response.ServiceUnavailableI18n(c, modulei18n.MsgServiceUnavailable)
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	var input createInput
+	if err := c.ShouldBindJSON(&input); err != nil {
+		response.BadRequestI18n(c, modulei18n.MsgInvalidPayload)
+		return
+	}
+
+	entity, err := h.svc.Create(c.Request.Context(), tenantID, service.__ENTITY__Input{
+		Name:        input.Name,
+		Description: input.Description,
+		Status:      input.Status,
+	})
+	if err != nil {
+		var i18nErr *i18n.I18nError
+		if errors.As(err, &i18nErr) {
+			response.BadRequestI18n(c, i18nErr.Key)
+			return
+		}
+		response.InternalErrorI18n(c, modulei18n.MsgCreateFailed)
+		return
+	}
+
+	response.CreatedI18n(c, modulei18n.MsgCreated, entity)
 }
 
-func (s *Service) Create(ctx context.Context, entity *models.{Entity}) error {
-    return s.repo.Create(ctx, entity)
+func (h *__ENTITY__Handler) Update(c *gin.Context) {
+	if h == nil || h.svc == nil {
+		response.ServiceUnavailableI18n(c, modulei18n.MsgServiceUnavailable)
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	id, err := hcommon.ParseUintParam(c, "id")
+	if err != nil || id == 0 {
+		response.BadRequestI18n(c, modulei18n.MsgInvalidID)
+		return
+	}
+
+	var input updateInput
+	if err := c.ShouldBindJSON(&input); err != nil {
+		response.BadRequestI18n(c, modulei18n.MsgInvalidPayload)
+		return
+	}
+
+	entity, err := h.svc.Update(c.Request.Context(), tenantID, id, service.__ENTITY__UpdateInput{
+		Name:        input.Name,
+		Description: input.Description,
+		Status:      input.Status,
+	})
+	if err != nil {
+		var i18nErr *i18n.I18nError
+		if errors.As(err, &i18nErr) {
+			if i18nErr.Key == modulei18n.Msg__ENTITY__NotFound {
+				response.NotFoundI18n(c, i18nErr.Key)
+			} else {
+				response.BadRequestI18n(c, i18nErr.Key)
+			}
+			return
+		}
+		response.InternalErrorI18n(c, modulei18n.MsgUpdateFailed)
+		return
+	}
+
+	response.SuccessI18n(c, modulei18n.MsgUpdated, entity)
 }
 
-func (s *Service) Update(ctx context.Context, id string, entity *models.{Entity}) error {
-    return s.repo.Update(ctx, id, entity)
+func (h *__ENTITY__Handler) Delete(c *gin.Context) {
+	if h == nil || h.svc == nil {
+		response.ServiceUnavailableI18n(c, modulei18n.MsgServiceUnavailable)
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	id, err := hcommon.ParseUintParam(c, "id")
+	if err != nil || id == 0 {
+		response.BadRequestI18n(c, modulei18n.MsgInvalidID)
+		return
+	}
+
+	if err := h.svc.Delete(c.Request.Context(), tenantID, id); err != nil {
+		var i18nErr *i18n.I18nError
+		if errors.As(err, &i18nErr) {
+			if i18nErr.Key == modulei18n.Msg__ENTITY__NotFound {
+				response.NotFoundI18n(c, i18nErr.Key)
+				return
+			}
+		}
+		response.InternalErrorI18n(c, modulei18n.MsgDeleteFailed)
+		return
+	}
+
+	response.SuccessI18n(c, modulei18n.MsgDeleted, gin.H{"id": id})
 }
 
-func (s *Service) Delete(ctx context.Context, id string) error {
-    return s.repo.Delete(ctx, id)
+func resolveTenantID(c *gin.Context) uint {
+	if c == nil {
+		return defaultTenantID
+	}
+	if tenantID, ok := hcommon.GetTenantID(c); ok && tenantID > 0 {
+		return tenantID
+	}
+	return defaultTenantID
 }
 ```
 
-### infra/repository/repo.go
+### 6. infra/repository/repository.go (数据仓库)
+
 ```go
 package repository
 
 import (
-    "context"
-    "gorm.io/gorm"
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/service"
 )
 
-type Repository struct {
-    db *gorm.DB
+type __ENTITY__Repository struct {
+	db *gorm.DB
 }
 
-func NewRepository(db *gorm.DB) *Repository {
-    return &Repository{db: db}
+func New__ENTITY__Repository(db *gorm.DB) *__ENTITY__Repository {
+	return &__ENTITY__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 *__ENTITY__Repository) List(ctx context.Context, tenantID uint) ([]models.__ENTITY__, error) {
+	var items []models.__ENTITY__
+	err := r.db.WithContext(ctx).
+		Where("tenant_id = ?", tenantID).
+		Order("created_at desc").
+		Find(&items).Error
+	return items, err
 }
 
-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 *__ENTITY__Repository) FindByID(tenantID, id uint) (*models.__ENTITY__, error) {
+	var entity models.__ENTITY__
+	err := r.db.Where("tenant_id = ? AND id = ?", tenantID, id).First(&entity).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, service.Err__ENTITY__NotFound
+	}
+	return &entity, err
 }
 
-func (r *Repository) Create(ctx context.Context, entity *models.{Entity}) error {
-    return r.db.Create(entity).Error
+func (r *__ENTITY__Repository) Create(ctx context.Context, entity *models.__ENTITY__) error {
+	return r.db.WithContext(ctx).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 *__ENTITY__Repository) Update(ctx context.Context, entity *models.__ENTITY__) error {
+	return r.db.WithContext(ctx).Save(entity).Error
 }
 
-func (r *Repository) Delete(ctx context.Context, id string) error {
-    return r.db.Delete(&models.{Entity}{}, "id = ?", id).Error
+func (r *__ENTITY__Repository) Delete(ctx context.Context, entity *models.__ENTITY__) error {
+	return r.db.WithContext(ctx).Delete(entity).Error
 }
 ```
 
-### i18n/i18n.go
+### 7. i18n/keys.go (翻译键)
+
+```go
+package modulei18n
+
+const (
+	// 实体操作消息
+	MsgCreated      = "__MODULE__.__ENTITY_LOWER__.created"
+	MsgUpdated      = "__MODULE__.__ENTITY_LOWER__.updated"
+	MsgDeleted      = "__MODULE__.__ENTITY_LOWER__.deleted"
+	Msg__ENTITY__NotFound = "__MODULE__.__ENTITY_LOWER__.notFound"
+	MsgLoadFailed   = "__MODULE__.__ENTITY_LOWER__.loadFailed"
+	MsgCreateFailed = "__MODULE__.__ENTITY_LOWER__.createFailed"
+	MsgUpdateFailed = "__MODULE__.__ENTITY_LOWER__.updateFailed"
+	MsgDeleteFailed = "__MODULE__.__ENTITY_LOWER__.deleteFailed"
+
+	// 验证消息
+	MsgNameRequired   = "__MODULE__.validation.nameRequired"
+	MsgStatusInvalid  = "__MODULE__.validation.statusInvalid"
+	MsgInvalidID      = "__MODULE__.validation.invalidId"
+	MsgInvalidPayload = "__MODULE__.validation.invalidPayload"
+
+	// 服务消息
+	MsgServiceUnavailable = "__MODULE__.service.unavailable"
+)
+```
+
+### 8. i18n/i18n.go (翻译注册)
+
 ```go
-package i18n
+package modulei18n
 
 import (
-    "embed"
-    "github.com/robsuncn/keystone/infra/i18n"
+	"embed"
+	"github.com/robsuncn/keystone/infra/i18n"
 )
 
 //go:embed locales/*.json
-var Translations embed.FS
+var translations embed.FS
 
-func init() {
-    // 注册模块翻译文件
-    i18n.MustLoadModuleTranslations("{module}", Translations)
+func RegisterLocales() error {
+	return i18n.LoadModuleTranslations("__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"
-)
-```
+### 9. i18n/locales/zh-CN.json
 
-### i18n/locales/zh-CN.json
 ```json
 {
-  "{module}": {
-    "item": {
-      "created": "{实体}创建成功",
-      "updated": "{实体}更新成功",
-      "deleted": "{实体}删除成功",
-      "notFound": "{实体}不存在",
-      "invalid": "{实体}数据无效",
-      "alreadyExists": "{实体}已存在"
+  "__MODULE__": {
+    "__ENTITY_LOWER__": {
+      "created": "__MODULE_TITLE__创建成功",
+      "updated": "__MODULE_TITLE__更新成功",
+      "deleted": "__MODULE_TITLE__删除成功",
+      "notFound": "__MODULE_TITLE__不存在",
+      "loadFailed": "加载__MODULE_TITLE__失败",
+      "createFailed": "创建__MODULE_TITLE__失败",
+      "updateFailed": "更新__MODULE_TITLE__失败",
+      "deleteFailed": "删除__MODULE_TITLE__失败"
     },
     "validation": {
       "nameRequired": "名称不能为空",
-      "nameTooLong": "名称长度不能超过 {{max}} 个字符"
+      "statusInvalid": "状态无效",
+      "invalidId": "无效的ID",
+      "invalidPayload": "请求数据格式错误"
+    },
+    "service": {
+      "unavailable": "服务暂不可用"
     }
   }
 }
 ```
 
-### i18n/locales/en-US.json
+### 10. 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"
+  "__MODULE__": {
+    "__ENTITY_LOWER__": {
+      "created": "__ENTITY__ created successfully",
+      "updated": "__ENTITY__ updated successfully",
+      "deleted": "__ENTITY__ deleted successfully",
+      "notFound": "__ENTITY__ not found",
+      "loadFailed": "Failed to load __ENTITY_LOWER__",
+      "createFailed": "Failed to create __ENTITY_LOWER__",
+      "updateFailed": "Failed to update __ENTITY_LOWER__",
+      "deleteFailed": "Failed to delete __ENTITY_LOWER__"
     },
     "validation": {
       "nameRequired": "Name is required",
-      "nameTooLong": "Name cannot exceed {{max}} characters"
+      "statusInvalid": "Invalid status",
+      "invalidId": "Invalid ID",
+      "invalidPayload": "Invalid request payload"
+    },
+    "service": {
+      "unavailable": "Service unavailable"
     }
   }
 }
 ```
 
-### 使用翻译的 service.go
+### 11. bootstrap/migrations/migrate.go
+
 ```go
-package service
+package migrations
 
 import (
-    "errors"
-    "github.com/gin-gonic/gin"
-    "github.com/robsuncn/keystone/infra/i18n"
-    modulei18n "app/internal/modules/{module}/i18n"
+	"gorm.io/gorm"
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
 )
 
-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))
+func Migrate(db *gorm.DB) error {
+	return db.AutoMigrate(&models.__ENTITY__{})
+}
+```
+
+### 12. bootstrap/seeds/seed.go
+
+```go
+package seeds
+
+import "gorm.io/gorm"
+
+func Seed(db *gorm.DB) error {
+	// 添加初始数据（可选）
+	return nil
+}
+```
+
+---
+
+## 前端模板
+
+### 1. types.ts (类型定义)
+
+```typescript
+export type __ENTITY__Status = 'active' | 'inactive'
+
+export interface __ENTITY__ {
+  id: number
+  name: string
+  description: string
+  status: __ENTITY__Status
+  created_at: string
+  updated_at: string
+}
+```
+
+### 2. services/api.ts (API 服务)
+
+```typescript
+import { api, type ApiResponse } from '@robsun/keystone-web-core'
+import type { __ENTITY__, __ENTITY__Status } from '../types'
+
+type ListResponse = {
+  items: __ENTITY__[]
+}
+
+export const list__ENTITY__s = async () => {
+  const { data } = await api.get<ApiResponse<ListResponse>>('/__MODULE__/__RESOURCE__')
+  return data.data.items
+}
+
+export const get__ENTITY__ = async (id: number) => {
+  const { data } = await api.get<ApiResponse<__ENTITY__>>(`/__MODULE__/__RESOURCE__/${id}`)
+  return data.data
+}
+
+export const create__ENTITY__ = async (payload: {
+  name: string
+  description?: string
+  status?: __ENTITY__Status
+}) => {
+  const { data } = await api.post<ApiResponse<__ENTITY__>>('/__MODULE__/__RESOURCE__', payload)
+  return data.data
+}
+
+export const update__ENTITY__ = async (
+  id: number,
+  payload: { name?: string; description?: string; status?: __ENTITY__Status }
+) => {
+  const { data } = await api.patch<ApiResponse<__ENTITY__>>(`/__MODULE__/__RESOURCE__/${id}`, payload)
+  return data.data
+}
+
+export const delete__ENTITY__ = async (id: number) => {
+  await api.delete<ApiResponse<{ id: number }>>(`/__MODULE__/__RESOURCE__/${id}`)
+}
+```
+
+### 3. routes.tsx (路由定义)
+
+```tsx
+import { lazy, Suspense, type ComponentType, type ReactElement } from 'react'
+import type { RouteObject } from 'react-router-dom'
+import { AppstoreOutlined } from '@ant-design/icons'
+import { Spin } from 'antd'
+
+const lazyNamed = <T extends Record<string, ComponentType>, K extends keyof T>(
+  factory: () => Promise<T>,
+  name: K
+) =>
+  lazy(async () => {
+    const module = await factory()
+    return { default: module[name] }
+  })
+
+const withSuspense = (element: ReactElement) => (
+  <Suspense
+    fallback={
+      <div style={{ padding: 24, display: 'flex', justifyContent: 'center' }}>
+        <Spin />
+      </div>
     }
-    return item, nil
+  >
+    {element}
+  </Suspense>
+)
+
+const __ENTITY__ListPage = lazyNamed(() => import('./pages/__ENTITY__ListPage'), '__ENTITY__ListPage')
+
+export const __MODULE__Routes: RouteObject[] = [
+  {
+    path: '__MODULE__',
+    element: <__ENTITY__ListPage />,
+    handle: {
+      menu: {
+        labelKey: '__MODULE__:menu.__RESOURCE__',
+        icon: <AppstoreOutlined />,
+        permission: '__MODULE__:__ENTITY_LOWER__:view',
+      },
+      breadcrumbKey: '__MODULE__:menu.__RESOURCE__',
+      permission: '__MODULE__:__ENTITY_LOWER__:view',
+      helpKey: '__MODULE__/__RESOURCE__',
+    },
+  },
+].map((route) => ({
+  ...route,
+  element: route.element ? withSuspense(route.element) : route.element,
+}))
+```
+
+### 4. pages/__ENTITY__ListPage.tsx (列表页)
+
+```tsx
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { App, Button, Card, Form, Input, Modal, Popconfirm, Select, Space, Table, Tag, Typography } from 'antd'
+import type { ColumnsType } from 'antd/es/table'
+import { useTranslation } from 'react-i18next'
+import dayjs from 'dayjs'
+import { list__ENTITY__s, create__ENTITY__, update__ENTITY__, delete__ENTITY__ } from '../services/api'
+import type { __ENTITY__, __ENTITY__Status } from '../types'
+
+type FormValues = {
+  name: string
+  description?: string
+  status: __ENTITY__Status
+}
+
+const statusColors: Record<__ENTITY__Status, string> = {
+  active: 'success',
+  inactive: 'default',
 }
 
-func (s *Service) Create(c *gin.Context, entity *models.{Entity}) error {
-    if entity.Name == "" {
-        return errors.New(i18n.T(c, modulei18n.KeyNameRequired))
+export function __ENTITY__ListPage() {
+  const { t } = useTranslation('__MODULE__')
+  const { t: tc } = useTranslation('common')
+  const { message } = App.useApp()
+  const [items, setItems] = useState<__ENTITY__[]>([])
+  const [loading, setLoading] = useState(false)
+  const [modalOpen, setModalOpen] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [editingItem, setEditingItem] = useState<__ENTITY__ | null>(null)
+  const [form] = Form.useForm<FormValues>()
+
+  const statusOptions = useMemo(
+    () => [
+      { value: 'active', label: t('status.active') },
+      { value: 'inactive', label: t('status.inactive') },
+    ],
+    [t]
+  )
+
+  const fetchItems = useCallback(async () => {
+    setLoading(true)
+    try {
+      const data = await list__ENTITY__s()
+      setItems(data)
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : t('messages.loadFailed')
+      message.error(detail)
+    } finally {
+      setLoading(false)
+    }
+  }, [message, t])
+
+  useEffect(() => {
+    void fetchItems()
+  }, [fetchItems])
+
+  const openCreate = useCallback(() => {
+    setEditingItem(null)
+    setModalOpen(true)
+  }, [])
+
+  const openEdit = useCallback((item: __ENTITY__) => {
+    setEditingItem(item)
+    setModalOpen(true)
+  }, [])
+
+  const closeModal = useCallback(() => {
+    setModalOpen(false)
+    setEditingItem(null)
+  }, [])
+
+  useEffect(() => {
+    if (!modalOpen) return
+    form.resetFields()
+    if (editingItem) {
+      form.setFieldsValue({
+        name: editingItem.name,
+        description: editingItem.description,
+        status: editingItem.status,
+      })
+    } else {
+      form.setFieldsValue({ status: 'active' })
+    }
+  }, [editingItem, form, modalOpen])
+
+  const handleSubmit = useCallback(async () => {
+    let values: FormValues
+    try {
+      values = await form.validateFields()
+    } catch {
+      return
+    }
+
+    const payload = {
+      name: values.name.trim(),
+      description: values.description?.trim() ?? '',
+      status: values.status,
     }
 
-    err := s.repo.Create(c, entity)
-    if err != nil {
-        return err
+    setSaving(true)
+    try {
+      if (editingItem) {
+        await update__ENTITY__(editingItem.id, payload)
+        message.success(t('messages.updateSuccess'))
+      } else {
+        await create__ENTITY__(payload)
+        message.success(t('messages.createSuccess'))
+      }
+      closeModal()
+      await fetchItems()
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : tc('messages.operationFailed')
+      message.error(detail)
+    } finally {
+      setSaving(false)
     }
+  }, [closeModal, editingItem, fetchItems, form, message, t, tc])
+
+  const handleDelete = useCallback(
+    async (id: number) => {
+      try {
+        await delete__ENTITY__(id)
+        await fetchItems()
+        message.success(t('messages.deleteSuccess'))
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : tc('messages.operationFailed')
+        message.error(detail)
+      }
+    },
+    [fetchItems, message, t, tc]
+  )
+
+  const columns: ColumnsType<__ENTITY__> = useMemo(
+    () => [
+      { title: t('table.name'), dataIndex: 'name', key: 'name' },
+      {
+        title: t('table.description'),
+        dataIndex: 'description',
+        key: 'description',
+        render: (value: string) =>
+          value ? <Typography.Text type="secondary">{value}</Typography.Text> : '-',
+      },
+      {
+        title: t('table.status'),
+        dataIndex: 'status',
+        key: 'status',
+        render: (value: __ENTITY__Status) => (
+          <Tag color={statusColors[value]}>{t(`status.${value}`)}</Tag>
+        ),
+      },
+      {
+        title: tc('table.updatedAt'),
+        dataIndex: 'updated_at',
+        key: 'updated_at',
+        render: (value: string) => (value ? dayjs(value).format('YYYY-MM-DD HH:mm') : '-'),
+      },
+      {
+        title: tc('table.actions'),
+        key: 'actions',
+        render: (_, record) => (
+          <Space>
+            <Button type="link" onClick={() => openEdit(record)}>
+              {tc('actions.edit')}
+            </Button>
+            <Popconfirm title={tc('confirm.deleteContent')} onConfirm={() => handleDelete(record.id)}>
+              <Button type="link" danger>
+                {tc('actions.delete')}
+              </Button>
+            </Popconfirm>
+          </Space>
+        ),
+      },
+    ],
+    [handleDelete, openEdit, t, tc]
+  )
+
+  return (
+    <Card
+      title={t('page.title')}
+      extra={
+        <Space>
+          <Button onClick={fetchItems} loading={loading}>
+            {tc('actions.refresh')}
+          </Button>
+          <Button type="primary" onClick={openCreate}>
+            {t('page.createButton')}
+          </Button>
+        </Space>
+      }
+    >
+      <Table<__ENTITY__>
+        rowKey="id"
+        loading={loading}
+        columns={columns}
+        dataSource={items}
+        pagination={false}
+      />
+
+      <Modal
+        title={editingItem ? tc('actions.edit') : tc('actions.create')}
+        open={modalOpen}
+        onCancel={closeModal}
+        onOk={handleSubmit}
+        confirmLoading={saving}
+        okText={editingItem ? tc('actions.save') : tc('actions.create')}
+        destroyOnHidden
+      >
+        <Form form={form} layout="vertical" initialValues={{ status: 'active' }}>
+          <Form.Item
+            label={t('form.nameLabel')}
+            name="name"
+            rules={[{ required: true, whitespace: true, message: tc('form.required') }]}
+          >
+            <Input placeholder={t('form.namePlaceholder')} allowClear />
+          </Form.Item>
+          <Form.Item label={t('form.descriptionLabel')} name="description">
+            <Input.TextArea rows={3} placeholder={t('form.descriptionPlaceholder')} />
+          </Form.Item>
+          <Form.Item
+            label={t('table.status')}
+            name="status"
+            rules={[{ required: true, message: tc('form.required') }]}
+          >
+            <Select options={statusOptions} />
+          </Form.Item>
+        </Form>
+      </Modal>
+    </Card>
+  )
+}
+```
+
+### 5. index.ts (模块注册)
+
+```typescript
+import { registerRoutes } from '@robsun/keystone-web-core'
+import { __MODULE__Routes } from './routes'
+
+// 注册翻译
+import './locales/zh-CN/__MODULE__.json'
+import './locales/en-US/__MODULE__.json'
+
+// 注册路由
+registerRoutes(__MODULE__Routes)
+```
 
-    // 可以在日志或审计中使用翻译消息
-    return nil
+### 6. locales/zh-CN/__MODULE__.json
+
+```json
+{
+  "menu": {
+    "__RESOURCE__": "__MODULE_TITLE__管理"
+  },
+  "page": {
+    "title": "__MODULE_TITLE__管理",
+    "createButton": "新建__MODULE_TITLE__"
+  },
+  "table": {
+    "name": "名称",
+    "description": "描述",
+    "status": "状态"
+  },
+  "form": {
+    "nameLabel": "名称",
+    "namePlaceholder": "请输入名称",
+    "descriptionLabel": "描述",
+    "descriptionPlaceholder": "请输入描述"
+  },
+  "status": {
+    "active": "启用",
+    "inactive": "禁用"
+  },
+  "messages": {
+    "loadFailed": "加载数据失败",
+    "createSuccess": "创建成功",
+    "updateSuccess": "更新成功",
+    "deleteSuccess": "删除成功"
+  }
+}
+```
+
+### 7. locales/en-US/__MODULE__.json
+
+```json
+{
+  "menu": {
+    "__RESOURCE__": "__MODULE_TITLE__ Management"
+  },
+  "page": {
+    "title": "__MODULE_TITLE__ Management",
+    "createButton": "Create __MODULE_TITLE__"
+  },
+  "table": {
+    "name": "Name",
+    "description": "Description",
+    "status": "Status"
+  },
+  "form": {
+    "nameLabel": "Name",
+    "namePlaceholder": "Enter name",
+    "descriptionLabel": "Description",
+    "descriptionPlaceholder": "Enter description"
+  },
+  "status": {
+    "active": "Active",
+    "inactive": "Inactive"
+  },
+  "messages": {
+    "loadFailed": "Failed to load data",
+    "createSuccess": "Created successfully",
+    "updateSuccess": "Updated successfully",
+    "deleteSuccess": "Deleted successfully"
+  }
+}
+```
+
+---
+
+## Ant Design v6 注意事项
+
+- `Space` 使用 `direction`（v6 已修复），不要用 `orientation`
+- `Modal` 使用 `destroyOnHidden`，不要用 `destroyOnClose`
+- `Drawer` 使用 `size`，不要用 `width`
+- `Table` 的 `columns` 使用 `ColumnsType<T>` 类型
+
+---
+
+# 高级业务模板
+
+> 以下模板覆盖复杂业务场景，基于实际项目经验提炼。
+
+---
+
+## 多实体关联模板
+
+> 适用场景：订单-订单项、文章-评论、商品-SKU 等主从关系。
+
+### 占位符说明（扩展）
+
+| 占位符 | 含义 | 示例 |
+|--------|------|------|
+| `__MASTER__` | 主实体名 (PascalCase) | `Order` |
+| `__MASTER_LOWER__` | 主实体名 (小写) | `order` |
+| `__DETAIL__` | 明细实体名 (PascalCase) | `OrderItem` |
+| `__DETAIL_LOWER__` | 明细实体名 (小写) | `orderitem` |
+
+### 1. 主实体模型 (domain/models/master.go)
+
+```go
+package models
+
+import "github.com/robsuncn/keystone/domain/models"
+
+type __MASTER__Status string
+
+const (
+	Status__MASTER__Draft     __MASTER__Status = "draft"
+	Status__MASTER__Submitted __MASTER__Status = "submitted"
+	Status__MASTER__Approved  __MASTER__Status = "approved"
+	Status__MASTER__Rejected  __MASTER__Status = "rejected"
+)
+
+func (s __MASTER__Status) IsValid() bool {
+	switch s {
+	case Status__MASTER__Draft, Status__MASTER__Submitted,
+		Status__MASTER__Approved, Status__MASTER__Rejected:
+		return true
+	default:
+		return false
+	}
+}
+
+type __MASTER__ struct {
+	models.BaseModel
+	Code        string           `gorm:"size:50;not null;uniqueIndex:idx___MASTER_LOWER___tenant_code" json:"code"`
+	Title       string           `gorm:"size:200;not null" json:"title"`
+	Status      __MASTER__Status `gorm:"size:20;not null;default:'draft'" json:"status"`
+	TotalAmount float64          `gorm:"type:decimal(18,2);default:0" json:"total_amount"`
+	Remark      string           `gorm:"size:500" json:"remark"`
+
+	// 关联
+	Items []__DETAIL__ `gorm:"foreignKey:__MASTER__ID" json:"items,omitempty"`
+}
+
+func (__MASTER__) TableName() string {
+	return "__MODULE_____MASTER_LOWER__s"
+}
+```
+
+### 2. 明细实体模型 (domain/models/detail.go)
+
+```go
+package models
+
+import "github.com/robsuncn/keystone/domain/models"
+
+type __DETAIL__ struct {
+	models.BaseModel
+	__MASTER__ID uint    `gorm:"not null;index" json:"__MASTER_LOWER___id"`
+	ProductName  string  `gorm:"size:200;not null" json:"product_name"`
+	Quantity     int     `gorm:"not null;default:1" json:"quantity"`
+	UnitPrice    float64 `gorm:"type:decimal(18,2);not null" json:"unit_price"`
+	Amount       float64 `gorm:"type:decimal(18,2);not null" json:"amount"`
+	SortOrder    int     `gorm:"default:0" json:"sort_order"`
+}
+
+func (__DETAIL__) TableName() string {
+	return "__MODULE_____DETAIL_LOWER__s"
+}
+
+// 计算金额
+func (d *__DETAIL__) CalcAmount() {
+	d.Amount = float64(d.Quantity) * d.UnitPrice
+}
+```
+
+### 3. Service 带事务的创建 (domain/service/service.go)
+
+```go
+package service
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
+)
+
+type __MASTER__Service struct {
+	db   *gorm.DB
+	repo __MASTER__Repository
+}
+
+type Create__MASTER__Input struct {
+	Title  string
+	Remark string
+	Items  []Create__DETAIL__Input
+}
+
+type Create__DETAIL__Input struct {
+	ProductName string
+	Quantity    int
+	UnitPrice   float64
+}
+
+func (s *__MASTER__Service) Create(
+	ctx context.Context,
+	tenantID uint,
+	input Create__MASTER__Input,
+) (*models.__MASTER__, error) {
+	// 验证
+	if strings.TrimSpace(input.Title) == "" {
+		return nil, ErrTitleRequired
+	}
+	if len(input.Items) == 0 {
+		return nil, ErrItemsRequired
+	}
+
+	var result *models.__MASTER__
+
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// 生成编号
+		code := fmt.Sprintf("ORD%s%04d", time.Now().Format("20060102"), time.Now().UnixNano()%10000)
+
+		// 创建主实体
+		master := &models.__MASTER__{
+			Code:   code,
+			Title:  strings.TrimSpace(input.Title),
+			Status: models.Status__MASTER__Draft,
+			Remark: strings.TrimSpace(input.Remark),
+		}
+		master.TenantID = tenantID
+
+		if err := tx.Create(master).Error; err != nil {
+			return err
+		}
+
+		// 创建明细并计算总金额
+		var totalAmount float64
+		for i, itemInput := range input.Items {
+			item := &models.__DETAIL__{
+				__MASTER__ID: master.ID,
+				ProductName:  strings.TrimSpace(itemInput.ProductName),
+				Quantity:     itemInput.Quantity,
+				UnitPrice:    itemInput.UnitPrice,
+				SortOrder:    i + 1,
+			}
+			item.TenantID = tenantID
+			item.CalcAmount()
+			totalAmount += item.Amount
+
+			if err := tx.Create(item).Error; err != nil {
+				return err
+			}
+		}
+
+		// 更新主表总金额
+		master.TotalAmount = totalAmount
+		if err := tx.Save(master).Error; err != nil {
+			return err
+		}
+
+		result = master
+		return nil
+	})
+
+	if err != nil {
+		return nil, err
+	}
+
+	// 重新加载关联
+	return s.repo.FindByIDWithItems(tenantID, result.ID)
+}
+```
+
+### 4. Repository 预加载查询 (infra/repository/repository.go)
+
+```go
+package repository
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	"github.com/robsuncn/keystone/infra/pagination"
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/service"
+)
+
+type __MASTER__Repository struct {
+	db *gorm.DB
+}
+
+func New__MASTER__Repository(db *gorm.DB) *__MASTER__Repository {
+	return &__MASTER__Repository{db: db}
+}
+
+// 列表查询（不加载明细）
+func (r *__MASTER__Repository) List(
+	ctx context.Context,
+	tenantID uint,
+	filter service.ListFilter,
+	pageReq pagination.Request,
+) ([]models.__MASTER__, int64, error) {
+	query := r.db.WithContext(ctx).
+		Model(&models.__MASTER__{}).
+		Where("tenant_id = ?", tenantID)
+
+	// 应用过滤
+	if filter.Status != nil {
+		query = query.Where("status = ?", *filter.Status)
+	}
+	if filter.Keyword != nil && *filter.Keyword != "" {
+		keyword := "%" + *filter.Keyword + "%"
+		query = query.Where("code LIKE ? OR title LIKE ?", keyword, keyword)
+	}
+
+	var items []models.__MASTER__
+	total, err := pagination.Paginate(query.Order("created_at desc"), pageReq, &items)
+	return items, total, err
+}
+
+// 单个查询（预加载明细）
+func (r *__MASTER__Repository) FindByIDWithItems(tenantID, id uint) (*models.__MASTER__, error) {
+	var entity models.__MASTER__
+	err := r.db.
+		Preload("Items", func(db *gorm.DB) *gorm.DB {
+			return db.Order("sort_order asc")
+		}).
+		Where("tenant_id = ? AND id = ?", tenantID, id).
+		First(&entity).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, service.Err__MASTER__NotFound
+	}
+	return &entity, err
+}
+
+// 删除主实体（级联删除明细）
+func (r *__MASTER__Repository) DeleteWithItems(ctx context.Context, tenantID, id uint) error {
+	return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		// 先删明细
+		if err := tx.Where("__MASTER_LOWER___id = ?", id).Delete(&models.__DETAIL__{}).Error; err != nil {
+			return err
+		}
+		// 再删主表
+		result := tx.Where("tenant_id = ? AND id = ?", tenantID, id).Delete(&models.__MASTER__{})
+		if result.RowsAffected == 0 {
+			return service.Err__MASTER__NotFound
+		}
+		return result.Error
+	})
+}
+```
+
+### 5. 前端类型定义 (types.ts)
+
+```typescript
+export type __MASTER__Status = 'draft' | 'submitted' | 'approved' | 'rejected'
+
+export interface __DETAIL__ {
+  id: number
+  __MASTER_LOWER___id: number
+  product_name: string
+  quantity: number
+  unit_price: number
+  amount: number
+  sort_order: number
+}
+
+export interface __MASTER__ {
+  id: number
+  code: string
+  title: string
+  status: __MASTER__Status
+  total_amount: number
+  remark: string
+  items?: __DETAIL__[]
+  created_at: string
+  updated_at: string
+}
+
+export interface Create__MASTER__Input {
+  title: string
+  remark?: string
+  items: {
+    product_name: string
+    quantity: number
+    unit_price: number
+  }[]
+}
+```
+
+### 6. 前端主从表单组件 (components/__MASTER__Form.tsx)
+
+```tsx
+import { useCallback, useEffect } from 'react'
+import { Button, Form, Input, InputNumber, Space, Table } from 'antd'
+import { DeleteOutlined, PlusOutlined } from '@ant-design/icons'
+import type { ColumnsType } from 'antd/es/table'
+import { useTranslation } from 'react-i18next'
+
+interface ItemRow {
+  key: string
+  product_name: string
+  quantity: number
+  unit_price: number
+  amount: number
+}
+
+interface FormValues {
+  title: string
+  remark?: string
+  items: ItemRow[]
+}
+
+interface Props {
+  initialValues?: Partial<FormValues>
+  onSubmit: (values: FormValues) => Promise<void>
+  loading?: boolean
+}
+
+export function __MASTER__Form({ initialValues, onSubmit, loading }: Props) {
+  const { t } = useTranslation('__MODULE__')
+  const { t: tc } = useTranslation('common')
+  const [form] = Form.useForm<FormValues>()
+  const items = Form.useWatch('items', form) || []
+
+  useEffect(() => {
+    if (initialValues) {
+      form.setFieldsValue(initialValues)
+    } else {
+      form.setFieldsValue({
+        items: [{ key: '1', product_name: '', quantity: 1, unit_price: 0, amount: 0 }],
+      })
+    }
+  }, [form, initialValues])
+
+  const addItem = useCallback(() => {
+    const currentItems = form.getFieldValue('items') || []
+    form.setFieldsValue({
+      items: [
+        ...currentItems,
+        { key: String(Date.now()), product_name: '', quantity: 1, unit_price: 0, amount: 0 },
+      ],
+    })
+  }, [form])
+
+  const removeItem = useCallback(
+    (key: string) => {
+      const currentItems = form.getFieldValue('items') || []
+      form.setFieldsValue({
+        items: currentItems.filter((item: ItemRow) => item.key !== key),
+      })
+    },
+    [form]
+  )
+
+  const updateAmount = useCallback(
+    (key: string) => {
+      const currentItems: ItemRow[] = form.getFieldValue('items') || []
+      const updated = currentItems.map((item) => {
+        if (item.key === key) {
+          return { ...item, amount: item.quantity * item.unit_price }
+        }
+        return item
+      })
+      form.setFieldsValue({ items: updated })
+    },
+    [form]
+  )
+
+  const totalAmount = items.reduce((sum: number, item: ItemRow) => sum + (item.amount || 0), 0)
+
+  const columns: ColumnsType<ItemRow> = [
+    {
+      title: t('form.productName'),
+      dataIndex: 'product_name',
+      render: (_, record, index) => (
+        <Form.Item
+          name={['items', index, 'product_name']}
+          rules={[{ required: true, message: tc('form.required') }]}
+          style={{ marginBottom: 0 }}
+        >
+          <Input placeholder={t('form.productNamePlaceholder')} />
+        </Form.Item>
+      ),
+    },
+    {
+      title: t('form.quantity'),
+      dataIndex: 'quantity',
+      width: 120,
+      render: (_, record, index) => (
+        <Form.Item name={['items', index, 'quantity']} style={{ marginBottom: 0 }}>
+          <InputNumber
+            min={1}
+            onChange={() => updateAmount(record.key)}
+            style={{ width: '100%' }}
+          />
+        </Form.Item>
+      ),
+    },
+    {
+      title: t('form.unitPrice'),
+      dataIndex: 'unit_price',
+      width: 140,
+      render: (_, record, index) => (
+        <Form.Item name={['items', index, 'unit_price']} style={{ marginBottom: 0 }}>
+          <InputNumber
+            min={0}
+            precision={2}
+            onChange={() => updateAmount(record.key)}
+            style={{ width: '100%' }}
+          />
+        </Form.Item>
+      ),
+    },
+    {
+      title: t('form.amount'),
+      dataIndex: 'amount',
+      width: 120,
+      render: (_, record, index) => (
+        <Form.Item name={['items', index, 'amount']} style={{ marginBottom: 0 }}>
+          <InputNumber disabled precision={2} style={{ width: '100%' }} />
+        </Form.Item>
+      ),
+    },
+    {
+      title: tc('table.actions'),
+      width: 80,
+      render: (_, record) => (
+        <Button
+          type="text"
+          danger
+          icon={<DeleteOutlined />}
+          onClick={() => removeItem(record.key)}
+          disabled={items.length <= 1}
+        />
+      ),
+    },
+  ]
+
+  const handleSubmit = async () => {
+    const values = await form.validateFields()
+    await onSubmit(values)
+  }
+
+  return (
+    <Form form={form} layout="vertical">
+      <Form.Item
+        label={t('form.title')}
+        name="title"
+        rules={[{ required: true, whitespace: true, message: tc('form.required') }]}
+      >
+        <Input placeholder={t('form.titlePlaceholder')} />
+      </Form.Item>
+
+      <Form.Item label={t('form.remark')} name="remark">
+        <Input.TextArea rows={2} placeholder={t('form.remarkPlaceholder')} />
+      </Form.Item>
+
+      <Form.Item label={t('form.items')} required>
+        <Table
+          rowKey="key"
+          columns={columns}
+          dataSource={items}
+          pagination={false}
+          size="small"
+          footer={() => (
+            <Space style={{ width: '100%', justifyContent: 'space-between' }}>
+              <Button type="dashed" icon={<PlusOutlined />} onClick={addItem}>
+                {t('form.addItem')}
+              </Button>
+              <span>
+                {t('form.totalAmount')}: <strong>¥{totalAmount.toFixed(2)}</strong>
+              </span>
+            </Space>
+          )}
+        />
+      </Form.Item>
+
+      <Form.Item>
+        <Button type="primary" onClick={handleSubmit} loading={loading}>
+          {tc('actions.submit')}
+        </Button>
+      </Form.Item>
+    </Form>
+  )
+}
+```
+
+---
+
+## 审批流业务模板
+
+> 适用场景：费用申请、请假审批、采购申请等需要审批的业务。
+
+### 1. 模型添加审批字段 (domain/models/entity.go)
+
+```go
+package models
+
+import "github.com/robsuncn/keystone/domain/models"
+
+type __ENTITY__Status string
+
+const (
+	Status__ENTITY__Draft     __ENTITY__Status = "draft"
+	Status__ENTITY__Pending   __ENTITY__Status = "pending"   // 审批中
+	Status__ENTITY__Approved  __ENTITY__Status = "approved"
+	Status__ENTITY__Rejected  __ENTITY__Status = "rejected"
+	Status__ENTITY__Cancelled __ENTITY__Status = "cancelled"
+)
+
+type __ENTITY__ struct {
+	models.BaseModel
+	Code               string           `gorm:"size:50;not null;uniqueIndex" json:"code"`
+	Title              string           `gorm:"size:200;not null" json:"title"`
+	Status             __ENTITY__Status `gorm:"size:20;not null;default:'draft'" json:"status"`
+	ApprovalInstanceID *uint            `gorm:"index" json:"approval_instance_id,omitempty"`
+	RejectReason       string           `gorm:"size:500" json:"reject_reason,omitempty"`
+	// ... 其他业务字段
+}
+```
+
+### 2. Service 提交审批 (domain/service/submit.go)
+
+```go
+package service
+
+import (
+	"context"
+	"fmt"
+
+	approval "github.com/robsuncn/keystone/domain/approval/service"
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
+)
+
+// 提交审批
+func (s *__ENTITY__Service) Submit(ctx context.Context, tenantID, id, userID uint) error {
+	entity, err := s.repo.FindByID(tenantID, id)
+	if err != nil {
+		return err
+	}
+
+	// 验证状态
+	if entity.Status != models.Status__ENTITY__Draft {
+		return ErrInvalidStatusForSubmit
+	}
+
+	// 创建审批实例
+	instance, err := s.approval.CreateInstance(ctx, approval.CreateInstanceInput{
+		TenantID:     tenantID,
+		BusinessType: "__MODULE___approval", // 审批业务类型，需在审批模块预先配置
+		BusinessID:   id,
+		ApplicantID:  userID,
+		Context: map[string]interface{}{
+			"code":  entity.Code,
+			"title": entity.Title,
+			// 其他审批表单需要展示的字段
+		},
+	})
+	if err != nil {
+		return fmt.Errorf("创建审批实例失败: %w", err)
+	}
+
+	// 更新业务状态
+	entity.Status = models.Status__ENTITY__Pending
+	entity.ApprovalInstanceID = &instance.ID
+	return s.repo.Update(ctx, entity)
+}
+
+// 撤回审批
+func (s *__ENTITY__Service) Cancel(ctx context.Context, tenantID, id, userID uint) error {
+	entity, err := s.repo.FindByID(tenantID, id)
+	if err != nil {
+		return err
+	}
+
+	if entity.Status != models.Status__ENTITY__Pending {
+		return ErrInvalidStatusForCancel
+	}
+
+	if entity.ApprovalInstanceID == nil {
+		return ErrNoApprovalInstance
+	}
+
+	// 取消审批实例
+	if err := s.approval.Cancel(ctx, *entity.ApprovalInstanceID, userID); err != nil {
+		return err
+	}
+
+	// 更新业务状态
+	entity.Status = models.Status__ENTITY__Draft
+	entity.ApprovalInstanceID = nil
+	return s.repo.Update(ctx, entity)
+}
+```
+
+### 3. 审批回调实现 (domain/service/callback.go)
+
+```go
+package service
+
+import (
+	"context"
+	"log/slog"
+
+	approval "github.com/robsuncn/keystone/domain/approval/service"
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/infra/repository"
+)
+
+const ApprovalBusinessType = "__MODULE___approval"
+
+// __ENTITY__ApprovalCallback 实现审批回调接口
+type __ENTITY__ApprovalCallback struct {
+	repo *repository.__ENTITY__Repository
+}
+
+func New__ENTITY__ApprovalCallback(repo *repository.__ENTITY__Repository) *__ENTITY__ApprovalCallback {
+	return &__ENTITY__ApprovalCallback{repo: repo}
+}
+
+// OnApproved 审批通过回调
+func (c *__ENTITY__ApprovalCallback) OnApproved(
+	ctx context.Context,
+	tenantID, businessID, approverID uint,
+) error {
+	entity, err := c.repo.FindByID(tenantID, businessID)
+	if err != nil {
+		return err
+	}
+
+	if entity.Status != models.Status__ENTITY__Pending {
+		slog.Warn("审批回调：状态不匹配",
+			"expected", models.Status__ENTITY__Pending,
+			"actual", entity.Status,
+		)
+		return nil // 幂等处理
+	}
+
+	entity.Status = models.Status__ENTITY__Approved
+	return c.repo.Update(ctx, entity)
+}
+
+// OnRejected 审批拒绝回调
+func (c *__ENTITY__ApprovalCallback) OnRejected(
+	ctx context.Context,
+	tenantID, businessID, approverID uint,
+	reason string,
+) error {
+	entity, err := c.repo.FindByID(tenantID, businessID)
+	if err != nil {
+		return err
+	}
+
+	if entity.Status != models.Status__ENTITY__Pending {
+		return nil // 幂等处理
+	}
+
+	entity.Status = models.Status__ENTITY__Rejected
+	entity.RejectReason = reason
+	return c.repo.Update(ctx, entity)
+}
+```
+
+### 4. Module 注册回调 (module.go)
+
+```go
+package __MODULE__
+
+import (
+	approval "github.com/robsuncn/keystone/domain/approval/service"
+	// ...
+)
+
+// RegisterApprovalCallback 在应用启动时调用
+func (m *Module) RegisterApprovalCallback(registry *approval.CallbackRegistry) {
+	callback := service.New__ENTITY__ApprovalCallback(m.repo)
+
+	// 包装为带重试的回调
+	retryable := approval.NewRetryableCallback(callback, approval.RetryConfig{
+		MaxRetries:     3,
+		InitialBackoff: time.Second,
+		MaxBackoff:     30 * time.Second,
+		BackoffFactor:  2.0,
+	})
+
+	registry.Register(service.ApprovalBusinessType, retryable)
+}
+```
+
+### 5. Handler 审批操作 (api/handler/approval.go)
+
+```go
+package handler
+
+import (
+	"github.com/gin-gonic/gin"
+	hcommon "github.com/robsuncn/keystone/api/handler/common"
+	"github.com/robsuncn/keystone/api/response"
+
+	modulei18n "__APP_NAME__/apps/server/internal/modules/__MODULE__/i18n"
+)
+
+// Submit 提交审批
+func (h *__ENTITY__Handler) Submit(c *gin.Context) {
+	if h == nil || h.svc == nil {
+		response.ServiceUnavailableI18n(c, modulei18n.MsgServiceUnavailable)
+		return
+	}
+	tenantID := resolveTenantID(c)
+	userID, _ := hcommon.GetUserID(c)
+
+	id, err := hcommon.ParseUintParam(c, "id")
+	if err != nil || id == 0 {
+		response.BadRequestI18n(c, modulei18n.MsgInvalidID)
+		return
+	}
+
+	if err := h.svc.Submit(c.Request.Context(), tenantID, id, userID); err != nil {
+		handleServiceError(c, err)
+		return
+	}
+
+	response.SuccessI18n(c, modulei18n.MsgSubmitted, nil)
+}
+
+// Cancel 撤回审批
+func (h *__ENTITY__Handler) Cancel(c *gin.Context) {
+	if h == nil || h.svc == nil {
+		response.ServiceUnavailableI18n(c, modulei18n.MsgServiceUnavailable)
+		return
+	}
+	tenantID := resolveTenantID(c)
+	userID, _ := hcommon.GetUserID(c)
+
+	id, err := hcommon.ParseUintParam(c, "id")
+	if err != nil || id == 0 {
+		response.BadRequestI18n(c, modulei18n.MsgInvalidID)
+		return
+	}
+
+	if err := h.svc.Cancel(c.Request.Context(), tenantID, id, userID); err != nil {
+		handleServiceError(c, err)
+		return
+	}
+
+	response.SuccessI18n(c, modulei18n.MsgCancelled, nil)
+}
+```
+
+### 6. 路由注册审批操作
+
+```go
+func (m *Module) RegisterRoutes(rg *gin.RouterGroup) {
+	h := handler.New__ENTITY__Handler(m.svc)
+	group := rg.Group("/__MODULE__")
+
+	// CRUD 路由
+	group.GET("/__RESOURCE__", h.List)
+	group.POST("/__RESOURCE__", h.Create)
+	group.GET("/__RESOURCE__/:id", h.Get)
+	group.PATCH("/__RESOURCE__/:id", h.Update)
+	group.DELETE("/__RESOURCE__/:id", h.Delete)
+
+	// 审批操作路由
+	group.POST("/__RESOURCE__/:id/submit", h.Submit)  // 提交审批
+	group.POST("/__RESOURCE__/:id/cancel", h.Cancel)  // 撤回审批
+}
+```
+
+### 7. 前端审批操作按钮 (components/ApprovalActions.tsx)
+
+```tsx
+import { useCallback, useState } from 'react'
+import { App, Button, Popconfirm, Space, Tag } from 'antd'
+import { CheckCircleOutlined, CloseCircleOutlined, SendOutlined, UndoOutlined } from '@ant-design/icons'
+import { useTranslation } from 'react-i18next'
+import type { __ENTITY__Status } from '../types'
+
+interface Props {
+  id: number
+  status: __ENTITY__Status
+  onSubmit: (id: number) => Promise<void>
+  onCancel: (id: number) => Promise<void>
+  onRefresh: () => void
+}
+
+const statusConfig: Record<__ENTITY__Status, { color: string; icon: React.ReactNode }> = {
+  draft: { color: 'default', icon: null },
+  pending: { color: 'processing', icon: <CloseCircleOutlined spin /> },
+  approved: { color: 'success', icon: <CheckCircleOutlined /> },
+  rejected: { color: 'error', icon: <CloseCircleOutlined /> },
+  cancelled: { color: 'default', icon: null },
+}
+
+export function ApprovalActions({ id, status, onSubmit, onCancel, onRefresh }: Props) {
+  const { t } = useTranslation('__MODULE__')
+  const { t: tc } = useTranslation('common')
+  const { message } = App.useApp()
+  const [loading, setLoading] = useState(false)
+
+  const handleSubmit = useCallback(async () => {
+    setLoading(true)
+    try {
+      await onSubmit(id)
+      message.success(t('messages.submitSuccess'))
+      onRefresh()
+    } catch (err) {
+      message.error(err instanceof Error ? err.message : tc('messages.operationFailed'))
+    } finally {
+      setLoading(false)
+    }
+  }, [id, message, onRefresh, onSubmit, t, tc])
+
+  const handleCancel = useCallback(async () => {
+    setLoading(true)
+    try {
+      await onCancel(id)
+      message.success(t('messages.cancelSuccess'))
+      onRefresh()
+    } catch (err) {
+      message.error(err instanceof Error ? err.message : tc('messages.operationFailed'))
+    } finally {
+      setLoading(false)
+    }
+  }, [id, message, onRefresh, onCancel, t, tc])
+
+  const config = statusConfig[status]
+
+  return (
+    <Space>
+      <Tag color={config.color} icon={config.icon}>
+        {t(`status.${status}`)}
+      </Tag>
+
+      {status === 'draft' && (
+        <Popconfirm title={t('confirm.submit')} onConfirm={handleSubmit}>
+          <Button type="primary" icon={<SendOutlined />} loading={loading} size="small">
+            {t('actions.submit')}
+          </Button>
+        </Popconfirm>
+      )}
+
+      {status === 'pending' && (
+        <Popconfirm title={t('confirm.cancel')} onConfirm={handleCancel}>
+          <Button icon={<UndoOutlined />} loading={loading} size="small">
+            {t('actions.cancel')}
+          </Button>
+        </Popconfirm>
+      )}
+    </Space>
+  )
+}
+```
+
+---
+
+## 导入/导出 Job 模板
+
+> 适用场景：批量导入数据、导出报表等异步任务。
+
+### 1. 导入 Job 实现 (domain/jobs/import.go)
+
+```go
+package jobs
+
+import (
+	"context"
+	"encoding/csv"
+	"fmt"
+	"io"
+	"strings"
+
+	"github.com/robsuncn/keystone/infra/jobs"
+	"github.com/robsuncn/keystone/infra/storage"
+
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/infra/repository"
+)
+
+const ImportJobType = "__MODULE___import"
+
+type Import__ENTITY__Job struct {
+	repo    *repository.__ENTITY__Repository
+	storage storage.Service
+}
+
+func NewImport__ENTITY__Job(repo *repository.__ENTITY__Repository, storage storage.Service) *Import__ENTITY__Job {
+	return &Import__ENTITY__Job{repo: repo, storage: storage}
+}
+
+func (j *Import__ENTITY__Job) Type() string {
+	return ImportJobType
+}
+
+func (j *Import__ENTITY__Job) Execute(ctx context.Context, params jobs.Params, progress jobs.ProgressReporter) error {
+	fileID := params.GetString("file_id")
+	tenantID := params.GetUint("tenant_id")
+
+	if fileID == "" {
+		return fmt.Errorf("file_id is required")
+	}
+
+	// 下载文件
+	progress.Update(5, "正在读取文件...")
+	reader, err := j.storage.Download(ctx, fileID)
+	if err != nil {
+		return fmt.Errorf("下载文件失败: %w", err)
+	}
+	defer reader.Close()
+
+	// 解析 CSV
+	progress.Update(10, "正在解析数据...")
+	csvReader := csv.NewReader(reader)
+	records, err := csvReader.ReadAll()
+	if err != nil {
+		return fmt.Errorf("解析 CSV 失败: %w", err)
+	}
+
+	if len(records) < 2 {
+		return fmt.Errorf("文件为空或只有表头")
+	}
+
+	// 跳过表头
+	dataRows := records[1:]
+	total := len(dataRows)
+	successCount := 0
+	errorRows := make([]string, 0)
+
+	// 批量处理
+	batchSize := 100
+	for i := 0; i < total; i += batchSize {
+		end := i + batchSize
+		if end > total {
+			end = total
+		}
+
+		batch := dataRows[i:end]
+		for rowIdx, row := range batch {
+			actualRow := i + rowIdx + 2 // +2 因为跳过表头且从1开始
+
+			if len(row) < 2 {
+				errorRows = append(errorRows, fmt.Sprintf("第%d行: 列数不足", actualRow))
+				continue
+			}
+
+			entity := &models.__ENTITY__{
+				Name:        strings.TrimSpace(row[0]),
+				Description: strings.TrimSpace(row[1]),
+				Status:      models.Status__ENTITY__Active,
+			}
+			entity.TenantID = tenantID
+
+			if entity.Name == "" {
+				errorRows = append(errorRows, fmt.Sprintf("第%d行: 名称不能为空", actualRow))
+				continue
+			}
+
+			if err := j.repo.Create(ctx, entity); err != nil {
+				errorRows = append(errorRows, fmt.Sprintf("第%d行: %s", actualRow, err.Error()))
+				continue
+			}
+
+			successCount++
+		}
+
+		// 更新进度
+		percent := 10 + int(float64(end)/float64(total)*85)
+		progress.Update(percent, fmt.Sprintf("已处理 %d/%d 条", end, total))
+	}
+
+	// 完成
+	progress.Update(100, fmt.Sprintf("导入完成: 成功 %d 条, 失败 %d 条", successCount, len(errorRows)))
+
+	// 如果有错误，记录到结果
+	if len(errorRows) > 0 {
+		progress.SetResult(map[string]interface{}{
+			"success_count": successCount,
+			"error_count":   len(errorRows),
+			"errors":        errorRows,
+		})
+	}
+
+	return nil
+}
+```
+
+### 2. 导出 Job 实现 (domain/jobs/export.go)
+
+```go
+package jobs
+
+import (
+	"bytes"
+	"context"
+	"encoding/csv"
+	"fmt"
+
+	"github.com/robsuncn/keystone/infra/jobs"
+	"github.com/robsuncn/keystone/infra/storage"
+
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/service"
+	"__APP_NAME__/apps/server/internal/modules/__MODULE__/infra/repository"
+)
+
+const ExportJobType = "__MODULE___export"
+
+type Export__ENTITY__Job struct {
+	repo    *repository.__ENTITY__Repository
+	storage storage.Service
+}
+
+func NewExport__ENTITY__Job(repo *repository.__ENTITY__Repository, storage storage.Service) *Export__ENTITY__Job {
+	return &Export__ENTITY__Job{repo: repo, storage: storage}
+}
+
+func (j *Export__ENTITY__Job) Type() string {
+	return ExportJobType
+}
+
+func (j *Export__ENTITY__Job) Execute(ctx context.Context, params jobs.Params, progress jobs.ProgressReporter) error {
+	tenantID := params.GetUint("tenant_id")
+	filter := service.ListFilter{
+		Status: params.GetStringPtr("status"),
+	}
+
+	// 查询数据
+	progress.Update(10, "正在查询数据...")
+	items, err := j.repo.ListAll(ctx, tenantID, filter)
+	if err != nil {
+		return fmt.Errorf("查询数据失败: %w", err)
+	}
+
+	if len(items) == 0 {
+		return fmt.Errorf("没有数据可导出")
+	}
+
+	// 生成 CSV
+	progress.Update(30, "正在生成文件...")
+	var buf bytes.Buffer
+	writer := csv.NewWriter(&buf)
+
+	// 写表头
+	if err := writer.Write([]string{"ID", "名称", "描述", "状态", "创建时间"}); err != nil {
+		return err
+	}
+
+	// 写数据
+	for i, item := range items {
+		row := []string{
+			fmt.Sprintf("%d", item.ID),
+			item.Name,
+			item.Description,
+			string(item.Status),
+			item.CreatedAt.Format("2006-01-02 15:04:05"),
+		}
+		if err := writer.Write(row); err != nil {
+			return err
+		}
+
+		if i%100 == 0 {
+			percent := 30 + int(float64(i)/float64(len(items))*50)
+			progress.Update(percent, fmt.Sprintf("已处理 %d/%d 条", i, len(items)))
+		}
+	}
+	writer.Flush()
+
+	// 上传文件
+	progress.Update(85, "正在保存文件...")
+	filename := fmt.Sprintf("export_%s_%d.csv", "__MODULE__", params.GetUint("job_id"))
+	fileID, err := j.storage.Upload(ctx, storage.UploadInput{
+		Filename:    filename,
+		ContentType: "text/csv",
+		Reader:      bytes.NewReader(buf.Bytes()),
+		Size:        int64(buf.Len()),
+	})
+	if err != nil {
+		return fmt.Errorf("上传文件失败: %w", err)
+	}
+
+	// 设置结果
+	progress.Update(100, "导出完成")
+	progress.SetResult(map[string]interface{}{
+		"file_id":  fileID,
+		"filename": filename,
+		"count":    len(items),
+	})
+
+	return nil
+}
+```
+
+### 3. Module 注册 Jobs (module.go)
+
+```go
+func (m *Module) RegisterJobs(reg *jobs.Registry) error {
+	if reg == nil {
+		return nil
+	}
+
+	// 注册导入 Job
+	importJob := modulejobs.NewImport__ENTITY__Job(m.repo, m.storage)
+	if err := reg.Register(importJob); err != nil {
+		return err
+	}
+
+	// 注册导出 Job
+	exportJob := modulejobs.NewExport__ENTITY__Job(m.repo, m.storage)
+	if err := reg.Register(exportJob); err != nil {
+		return err
+	}
+
+	return nil
+}
+```
+
+### 4. Handler 创建导入导出任务 (api/handler/jobs.go)
+
+```go
+package handler
+
+import (
+	"github.com/gin-gonic/gin"
+	hcommon "github.com/robsuncn/keystone/api/handler/common"
+	"github.com/robsuncn/keystone/api/response"
+	"github.com/robsuncn/keystone/infra/jobs"
+
+	modulei18n "__APP_NAME__/apps/server/internal/modules/__MODULE__/i18n"
+	modulejobs "__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/jobs"
+)
+
+type ImportInput struct {
+	FileID string `json:"file_id" binding:"required"`
+}
+
+// StartImport 开始导入
+func (h *__ENTITY__Handler) StartImport(c *gin.Context) {
+	tenantID := resolveTenantID(c)
+	userID, _ := hcommon.GetUserID(c)
+
+	var input ImportInput
+	if err := c.ShouldBindJSON(&input); err != nil {
+		response.BadRequestI18n(c, modulei18n.MsgInvalidPayload)
+		return
+	}
+
+	job, err := h.jobs.Create(c.Request.Context(), jobs.CreateInput{
+		Type:     modulejobs.ImportJobType,
+		TenantID: tenantID,
+		UserID:   userID,
+		Params: map[string]interface{}{
+			"file_id":   input.FileID,
+			"tenant_id": tenantID,
+		},
+	})
+	if err != nil {
+		response.InternalErrorI18n(c, modulei18n.MsgJobCreateFailed)
+		return
+	}
+
+	response.Success(c, job)
+}
+
+type ExportInput struct {
+	Status *string `json:"status"`
+}
+
+// StartExport 开始导出
+func (h *__ENTITY__Handler) StartExport(c *gin.Context) {
+	tenantID := resolveTenantID(c)
+	userID, _ := hcommon.GetUserID(c)
+
+	var input ExportInput
+	_ = c.ShouldBindJSON(&input)
+
+	job, err := h.jobs.Create(c.Request.Context(), jobs.CreateInput{
+		Type:     modulejobs.ExportJobType,
+		TenantID: tenantID,
+		UserID:   userID,
+		Params: map[string]interface{}{
+			"tenant_id": tenantID,
+			"status":    input.Status,
+		},
+	})
+	if err != nil {
+		response.InternalErrorI18n(c, modulei18n.MsgJobCreateFailed)
+		return
+	}
+
+	response.Success(c, job)
+}
+```
+
+### 5. 前端导入组件 (components/ImportButton.tsx)
+
+```tsx
+import { useCallback, useState } from 'react'
+import { App, Button, Modal, Progress, Space, Upload } from 'antd'
+import { UploadOutlined, DownloadOutlined } from '@ant-design/icons'
+import type { UploadFile } from 'antd'
+import { useTranslation } from 'react-i18next'
+import { uploadFile } from '@robsun/keystone-web-core'
+import { startImport, getJob } from '../services/api'
+
+interface Props {
+  onComplete: () => void
+}
+
+export function ImportButton({ onComplete }: Props) {
+  const { t } = useTranslation('__MODULE__')
+  const { t: tc } = useTranslation('common')
+  const { message } = App.useApp()
+  const [modalOpen, setModalOpen] = useState(false)
+  const [uploading, setUploading] = useState(false)
+  const [jobId, setJobId] = useState<number | null>(null)
+  const [progress, setProgress] = useState(0)
+  const [progressText, setProgressText] = useState('')
+
+  const handleUpload = useCallback(
+    async (file: UploadFile) => {
+      if (!file.originFileObj) return
+
+      setUploading(true)
+      try {
+        // 上传文件
+        const fileId = await uploadFile(file.originFileObj)
+
+        // 创建导入任务
+        const job = await startImport({ file_id: fileId })
+        setJobId(job.id)
+
+        // 轮询进度
+        const pollProgress = async () => {
+          const jobStatus = await getJob(job.id)
+          setProgress(jobStatus.progress || 0)
+          setProgressText(jobStatus.message || '')
+
+          if (jobStatus.status === 'completed') {
+            message.success(t('messages.importSuccess'))
+            setModalOpen(false)
+            onComplete()
+          } else if (jobStatus.status === 'failed') {
+            message.error(jobStatus.error || t('messages.importFailed'))
+          } else {
+            setTimeout(pollProgress, 1000)
+          }
+        }
+        pollProgress()
+      } catch (err) {
+        message.error(err instanceof Error ? err.message : tc('messages.operationFailed'))
+      } finally {
+        setUploading(false)
+      }
+    },
+    [message, onComplete, t, tc]
+  )
+
+  const downloadTemplate = useCallback(() => {
+    const csv = 'Name,Description\nExample 1,Description 1\nExample 2,Description 2'
+    const blob = new Blob([csv], { type: 'text/csv' })
+    const url = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = url
+    a.download = 'import_template.csv'
+    a.click()
+    URL.revokeObjectURL(url)
+  }, [])
+
+  return (
+    <>
+      <Button icon={<UploadOutlined />} onClick={() => setModalOpen(true)}>
+        {t('actions.import')}
+      </Button>
+
+      <Modal
+        title={t('import.title')}
+        open={modalOpen}
+        onCancel={() => setModalOpen(false)}
+        footer={null}
+        destroyOnHidden
+      >
+        <Space direction="vertical" style={{ width: '100%' }}>
+          <Button icon={<DownloadOutlined />} onClick={downloadTemplate}>
+            {t('import.downloadTemplate')}
+          </Button>
+
+          <Upload
+            accept=".csv"
+            maxCount={1}
+            beforeUpload={(file) => {
+              handleUpload({ originFileObj: file } as UploadFile)
+              return false
+            }}
+            disabled={uploading || jobId !== null}
+          >
+            <Button icon={<UploadOutlined />} loading={uploading}>
+              {t('import.selectFile')}
+            </Button>
+          </Upload>
+
+          {jobId && (
+            <div>
+              <Progress percent={progress} />
+              <p>{progressText}</p>
+            </div>
+          )}
+        </Space>
+      </Modal>
+    </>
+  )
+}
+```
+
+---
+
+## 前端高级组件示例
+
+### 1. ProTable 带分页过滤 (pages/__ENTITY__ProTablePage.tsx)
+
+```tsx
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { App, Button, Card, Input, Select, Space, Tag } from 'antd'
+import { PlusOutlined, ReloadOutlined, SearchOutlined } from '@ant-design/icons'
+import type { ColumnsType } from 'antd/es/table'
+import { useTranslation } from 'react-i18next'
+import { ProTable, type ProTableProps } from '@robsun/keystone-web-core'
+import dayjs from 'dayjs'
+import { list__ENTITY__s } from '../services/api'
+import type { __ENTITY__, __ENTITY__Status } from '../types'
+
+const statusColors: Record<__ENTITY__Status, string> = {
+  active: 'success',
+  inactive: 'default',
+}
+
+export function __ENTITY__ProTablePage() {
+  const { t } = useTranslation('__MODULE__')
+  const { t: tc } = useTranslation('common')
+  const { message } = App.useApp()
+
+  const [loading, setLoading] = useState(false)
+  const [data, setData] = useState<__ENTITY__[]>([])
+  const [total, setTotal] = useState(0)
+  const [page, setPage] = useState(1)
+  const [pageSize, setPageSize] = useState(10)
+  const [filters, setFilters] = useState<{ keyword?: string; status?: __ENTITY__Status }>({})
+
+  const fetchData = useCallback(async () => {
+    setLoading(true)
+    try {
+      const result = await list__ENTITY__s({
+        page,
+        page_size: pageSize,
+        ...filters,
+      })
+      setData(result.items)
+      setTotal(result.total)
+    } catch (err) {
+      message.error(err instanceof Error ? err.message : t('messages.loadFailed'))
+    } finally {
+      setLoading(false)
+    }
+  }, [filters, message, page, pageSize, t])
+
+  useEffect(() => {
+    void fetchData()
+  }, [fetchData])
+
+  const columns: ColumnsType<__ENTITY__> = useMemo(
+    () => [
+      { title: 'ID', dataIndex: 'id', key: 'id', width: 80 },
+      { title: t('table.name'), dataIndex: 'name', key: 'name' },
+      { title: t('table.description'), dataIndex: 'description', key: 'description', ellipsis: true },
+      {
+        title: t('table.status'),
+        dataIndex: 'status',
+        key: 'status',
+        width: 100,
+        render: (status: __ENTITY__Status) => (
+          <Tag color={statusColors[status]}>{t(`status.${status}`)}</Tag>
+        ),
+      },
+      {
+        title: tc('table.createdAt'),
+        dataIndex: 'created_at',
+        key: 'created_at',
+        width: 180,
+        render: (value: string) => dayjs(value).format('YYYY-MM-DD HH:mm'),
+      },
+      {
+        title: tc('table.actions'),
+        key: 'actions',
+        width: 150,
+        render: (_, record) => (
+          <Space>
+            <Button type="link" size="small">
+              {tc('actions.edit')}
+            </Button>
+            <Button type="link" size="small" danger>
+              {tc('actions.delete')}
+            </Button>
+          </Space>
+        ),
+      },
+    ],
+    [t, tc]
+  )
+
+  const toolbar = (
+    <Space wrap>
+      <Input
+        placeholder={t('filter.keyword')}
+        prefix={<SearchOutlined />}
+        allowClear
+        onChange={(e) => setFilters((prev) => ({ ...prev, keyword: e.target.value || undefined }))}
+        style={{ width: 200 }}
+      />
+      <Select
+        placeholder={t('filter.status')}
+        allowClear
+        onChange={(value) => setFilters((prev) => ({ ...prev, status: value }))}
+        options={[
+          { value: 'active', label: t('status.active') },
+          { value: 'inactive', label: t('status.inactive') },
+        ]}
+        style={{ width: 120 }}
+      />
+      <Button icon={<ReloadOutlined />} onClick={fetchData}>
+        {tc('actions.refresh')}
+      </Button>
+      <Button type="primary" icon={<PlusOutlined />}>
+        {t('page.createButton')}
+      </Button>
+    </Space>
+  )
+
+  return (
+    <Card title={t('page.title')} extra={toolbar}>
+      <ProTable<__ENTITY__>
+        rowKey="id"
+        loading={loading}
+        columns={columns}
+        dataSource={data}
+        pagination={{
+          current: page,
+          pageSize,
+          total,
+          showSizeChanger: true,
+          showQuickJumper: true,
+          showTotal: (total) => tc('pagination.total', { total }),
+          onChange: (p, ps) => {
+            setPage(p)
+            setPageSize(ps)
+          },
+        }}
+      />
+    </Card>
+  )
+}
+```
+
+### 2. 数据导入向导 (components/__ENTITY__Importer.tsx)
+
+```tsx
+import { useCallback, useState } from 'react'
+import { App, Modal } from 'antd'
+import { useTranslation } from 'react-i18next'
+import {
+  DataImporter,
+  type ColumnMapping,
+  type ImportResult,
+  type ValidationResult,
+} from '@robsun/keystone-web-core'
+import { batchCreate__ENTITY__s } from '../services/api'
+
+interface Props {
+  open: boolean
+  onClose: () => void
+  onComplete: () => void
+}
+
+const columns: ColumnMapping[] = [
+  { field: 'name', label: '名称', required: true },
+  { field: 'description', label: '描述', required: false },
+  { field: 'status', label: '状态', required: false, defaultValue: 'active' },
+]
+
+export function __ENTITY__Importer({ open, onClose, onComplete }: Props) {
+  const { t } = useTranslation('__MODULE__')
+  const { message } = App.useApp()
+  const [importing, setImporting] = useState(false)
+
+  const handleValidate = useCallback(async (data: Record<string, unknown>[]): Promise<ValidationResult> => {
+    const errors: { row: number; field: string; message: string }[] = []
+
+    data.forEach((row, index) => {
+      if (!row.name || String(row.name).trim() === '') {
+        errors.push({ row: index + 1, field: 'name', message: '名称不能为空' })
+      }
+      if (row.status && !['active', 'inactive'].includes(String(row.status))) {
+        errors.push({ row: index + 1, field: 'status', message: '状态值无效' })
+      }
+    })
+
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings: [],
+    }
+  }, [])
+
+  const handleImport = useCallback(
+    async (data: Record<string, unknown>[]): Promise<ImportResult> => {
+      setImporting(true)
+      try {
+        const items = data.map((row) => ({
+          name: String(row.name).trim(),
+          description: row.description ? String(row.description).trim() : '',
+          status: (row.status as 'active' | 'inactive') || 'active',
+        }))
+
+        const result = await batchCreate__ENTITY__s(items)
+
+        message.success(t('messages.importSuccess'))
+        onComplete()
+
+        return {
+          success: true,
+          imported: result.created,
+          failed: 0,
+          errors: [],
+        }
+      } catch (err) {
+        return {
+          success: false,
+          imported: 0,
+          failed: data.length,
+          errors: [{ row: 0, field: '', message: err instanceof Error ? err.message : '导入失败' }],
+        }
+      } finally {
+        setImporting(false)
+      }
+    },
+    [message, onComplete, t]
+  )
+
+  return (
+    <Modal
+      title={t('import.title')}
+      open={open}
+      onCancel={onClose}
+      footer={null}
+      width={800}
+      destroyOnHidden
+    >
+      <DataImporter
+        columns={columns}
+        onValidate={handleValidate}
+        onImport={handleImport}
+        loading={importing}
+        templateFileName="__MODULE___import_template.csv"
+      />
+    </Modal>
+  )
 }
 ```