@robsun/create-keystone-app 0.2.15 → 0.4.1

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

@@ -1,2710 +0,0 @@
-# Keystone 代码模板
-
-> 所有模板基于 example 模块实际代码，使用占位符标记变量部分。
-> 复制后替换占位符即可运行。
-
-## 占位符说明
-
-| 占位符 | 含义 | 示例 |
-|--------|------|------|
-| `__MODULE__` | 模块名 (小写) | `order`, `product` |
-| `__MODULE_TITLE__` | 模块中文名 | `订单`, `商品` |
-| `__ENTITY__` | 实体名 (PascalCase) | `Order`, `Product` |
-| `__ENTITY_LOWER__` | 实体名 (小写) | `order`, `product` |
-| `__RESOURCE__` | 资源名 (复数小写) | `orders`, `products` |
-| `__APP_NAME__` | 应用名 (go.mod 中定义) | 脚手架自动替换 |
-
----
-
-## 后端模板
-
-### 1. module.go (模块入口)
-
-```go
-package __MODULE__
-
-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"
-)
-
-type Module struct {
-	svc *service.__ENTITY__Service
-}
-
-func NewModule() *Module {
-	return &Module{}
-}
-
-func (m *Module) Name() string {
-	return "__MODULE__"
-}
-
-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)
-}
-
-func (m *Module) RegisterModels() []interface{} {
-	return []interface{}{&models.__ENTITY__{}}
-}
-
-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
-}
-
-func (m *Module) RegisterI18n() error {
-	return modulei18n.RegisterLocales()
-}
-
-func (m *Module) RegisterJobs(_ *jobs.Registry) error {
-	return nil
-}
-
-func (m *Module) Migrate(db *gorm.DB) error {
-	if db == nil {
-		return nil
-	}
-	m.ensureServices(db)
-	return migrations.Migrate(db)
-}
-
-func (m *Module) Seed(db *gorm.DB) error {
-	if db == nil {
-		return nil
-	}
-	m.ensureServices(db)
-	return seeds.Seed(db)
-}
-
-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)
-}
-```
-
-### 2. domain/models/entity.go (模型)
-
-```go
-package models
-
-import "github.com/robsuncn/keystone/domain/models"
-
-type __ENTITY__Status string
-
-const (
-	Status__ENTITY__Active   __ENTITY__Status = "active"
-	Status__ENTITY__Inactive __ENTITY__Status = "inactive"
-)
-
-func (s __ENTITY__Status) IsValid() bool {
-	switch s {
-	case Status__ENTITY__Active, Status__ENTITY__Inactive:
-		return true
-	default:
-		return false
-	}
-}
-
-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 (服务层)
-
-```go
-package service
-
-import (
-	"context"
-	"strings"
-
-	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
-)
-
-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
-}
-
-type __ENTITY__Input struct {
-	Name        string
-	Description string
-	Status      models.__ENTITY__Status
-}
-
-type __ENTITY__UpdateInput struct {
-	Name        *string
-	Description *string
-	Status      *models.__ENTITY__Status
-}
-
-func New__ENTITY__Service(repo __ENTITY__Repository) *__ENTITY__Service {
-	return &__ENTITY__Service{repo: repo}
-}
-
-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 (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)
-}
-```
-
-### 4. domain/service/errors.go (错误定义)
-
-```go
-package service
-
-import (
-	"github.com/robsuncn/keystone/infra/i18n"
-	modulei18n "__APP_NAME__/apps/server/internal/modules/__MODULE__/i18n"
-)
-
-var (
-	Err__ENTITY__NotFound = &i18n.I18nError{Key: modulei18n.Msg__ENTITY__NotFound}
-	ErrNameRequired       = &i18n.I18nError{Key: modulei18n.MsgNameRequired}
-	ErrStatusInvalid      = &i18n.I18nError{Key: modulei18n.MsgStatusInvalid}
-)
-```
-
-### 5. api/handler/handler.go (HTTP 处理器)
-
-```go
-package handler
-
-import (
-	"errors"
-
-	"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"
-
-	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
-}
-
-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 updateInput struct {
-	Name        *string               `json:"name"`
-	Description *string               `json:"description"`
-	Status      *models.__ENTITY__Status `json:"status"`
-}
-
-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 (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 (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 (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 (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 resolveTenantID(c *gin.Context) uint {
-	if c == nil {
-		return defaultTenantID
-	}
-	if tenantID, ok := hcommon.GetTenantID(c); ok && tenantID > 0 {
-		return tenantID
-	}
-	return defaultTenantID
-}
-```
-
-### 6. infra/repository/repository.go (数据仓库)
-
-```go
-package repository
-
-import (
-	"context"
-	"errors"
-
-	"gorm.io/gorm"
-
-	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
-	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/service"
-)
-
-type __ENTITY__Repository struct {
-	db *gorm.DB
-}
-
-func New__ENTITY__Repository(db *gorm.DB) *__ENTITY__Repository {
-	return &__ENTITY__Repository{db: db}
-}
-
-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 *__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 *__ENTITY__Repository) Create(ctx context.Context, entity *models.__ENTITY__) error {
-	return r.db.WithContext(ctx).Create(entity).Error
-}
-
-func (r *__ENTITY__Repository) Update(ctx context.Context, entity *models.__ENTITY__) error {
-	return r.db.WithContext(ctx).Save(entity).Error
-}
-
-func (r *__ENTITY__Repository) Delete(ctx context.Context, entity *models.__ENTITY__) error {
-	return r.db.WithContext(ctx).Delete(entity).Error
-}
-```
-
-### 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 modulei18n
-
-import (
-	"embed"
-	"github.com/robsuncn/keystone/infra/i18n"
-)
-
-//go:embed locales/*.json
-var translations embed.FS
-
-func RegisterLocales() error {
-	return i18n.LoadModuleTranslations("__MODULE__", translations)
-}
-```
-
-### 9. i18n/locales/zh-CN.json
-
-```json
-{
-  "__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": "名称不能为空",
-      "statusInvalid": "状态无效",
-      "invalidId": "无效的ID",
-      "invalidPayload": "请求数据格式错误"
-    },
-    "service": {
-      "unavailable": "服务暂不可用"
-    }
-  }
-}
-```
-
-### 10. i18n/locales/en-US.json
-
-```json
-{
-  "__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",
-      "statusInvalid": "Invalid status",
-      "invalidId": "Invalid ID",
-      "invalidPayload": "Invalid request payload"
-    },
-    "service": {
-      "unavailable": "Service unavailable"
-    }
-  }
-}
-```
-
-### 11. bootstrap/migrations/migrate.go
-
-```go
-package migrations
-
-import (
-	"gorm.io/gorm"
-	"__APP_NAME__/apps/server/internal/modules/__MODULE__/domain/models"
-)
-
-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>
-    }
-  >
-    {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',
-}
-
-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,
-    }
-
-    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)
-```
-
-### 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>
-  )
-}
-```