@robsun/create-keystone-app 0.2.13 → 0.4.0

package/template/.claude/skills/keystone-implement/references/PATTERNS.md

@@ -0,0 +1,1088 @@
+# Keystone 代码模式库
+
+---
+
+## 一、架构概览
+
+### 目录结构
+
+**后端：**
+```
+apps/server/internal/modules/{module}/
+├── module.go              # 模块入口
+├── api/handler/           # HTTP Handler
+├── domain/models/         # 数据模型
+├── domain/service/        # 业务逻辑 + errors.go
+├── infra/repository/      # 数据库操作
+└── i18n/                  # keys.go + i18n.go + locales/
+```
+
+**前端：**
+```
+apps/web/src/modules/{module}/
+├── index.ts               # 模块注册
+├── routes.tsx             # 路由配置
+├── types.ts               # 类型定义
+├── services/api.ts        # API 调用
+├── pages/                 # 页面组件
+└── locales/               # i18n 文件
+```
+
+### 分层职责
+
+| 层 | 职责 | 禁止 |
+|---|------|------|
+| Handler | 请求解析、响应格式化 | 业务逻辑、直接操作 DB |
+| Service | 业务逻辑、数据验证 | 直接操作 DB、HTTP 相关 |
+| Repository | 数据库操作、租户过滤 | 业务逻辑 |
+| Model | 数据结构、枚举验证 | 业务逻辑 |
+
+### 核心依赖
+
+| 包 | 用途 |
+|---|------|
+| `github.com/robsuncn/keystone/api/response` | 统一响应 |
+| `github.com/robsuncn/keystone/api/handler/common` | Handler 辅助 |
+| `github.com/robsuncn/keystone/domain/models` | BaseModel |
+| `@robsun/keystone-web-core` | api, registerModule, loadModuleLocales |
+
+---
+
+## 二、约定
+
+### 命名约定
+
+| 对象 | 后端 | 前端 |
+|------|------|------|
+| 目录 | kebab-case | kebab-case |
+| 文件 | snake_case (.go) | PascalCase (.tsx) / camelCase (.ts) |
+| 类型 | PascalCase | PascalCase |
+| 函数 | PascalCase | camelCase |
+| 变量 | camelCase | camelCase |
+| DB 表 | snake_case 复数 | - |
+| JSON | snake_case | - |
+| i18n key | `module.category.name` | `category.name` |
+
+### 字段类型映射
+
+| YAML | Go | TypeScript | GORM |
+|------|-----|------------|------|
+| string | string | string | `gorm:"size:200"` |
+| text | string | string | `gorm:"type:text"` |
+| integer | int | number | - |
+| decimal | float64 | number | `gorm:"type:decimal(10,2)"` |
+| boolean | bool | boolean | - |
+| date | time.Time | string | `gorm:"type:date"` |
+| datetime | time.Time | string | - |
+| enum | 自定义类型 | 联合类型 | `gorm:"size:20"` |
+
+### 占位符
+
+| 占位符 | 说明 | 示例 |
+|--------|------|------|
+| `{module}` | 模块名小写 | `customer` |
+| `{module-kebab}` | kebab-case | `customer-order` |
+| `{Entity}` | PascalCase | `Customer` |
+| `{table_name}` | snake_case 复数 | `customers` |
+
+---
+
+## 三、后端模式
+
+### B1: Module 入口
+
+```go
+package {module}
+
+import (
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/robsuncn/keystone/domain/permissions"
+	"github.com/robsuncn/keystone/infra/jobs"
+
+	{module}handler "__APP_NAME__/apps/server/internal/modules/{module}/api/handler"
+	{module}models "__APP_NAME__/apps/server/internal/modules/{module}/domain/models"
+	{module}service "__APP_NAME__/apps/server/internal/modules/{module}/domain/service"
+	{module}migrations "__APP_NAME__/apps/server/internal/modules/{module}/bootstrap/migrations"
+	{module}repository "__APP_NAME__/apps/server/internal/modules/{module}/infra/repository"
+)
+
+type Module struct {
+	items *{module}service.ItemService
+}
+
+func NewModule() *Module {
+	return &Module{}
+}
+
+func (m *Module) Name() string {
+	return "{module-kebab}"
+}
+
+func (m *Module) RegisterRoutes(rg *gin.RouterGroup) {
+	if rg == nil || m == nil {
+		return
+	}
+	handler := {module}handler.NewItemHandler(m.items)
+	if handler == nil {
+		return
+	}
+	group := rg.Group("/{module-kebab}")
+	group.GET("/items", handler.List)
+	group.POST("/items", handler.Create)
+	group.PATCH("/items/:id", handler.Update)
+	group.DELETE("/items/:id", handler.Delete)
+}
+
+func (m *Module) RegisterModels() []interface{} {
+	return []interface{}{&{module}models.{Entity}{}}
+}
+
+func (m *Module) RegisterPermissions(reg *permissions.Registry) error {
+	if reg == nil {
+		return nil
+	}
+	if err := reg.CreateMenuI18n("{module-kebab}:item", "{Entity} Items",
+		"permission.{module}.item", "{module-kebab}", 10); err != nil {
+		return err
+	}
+	if err := reg.CreateActionI18n("{module-kebab}:item:view", "View Items",
+		"permission.{module}.item.view", "{module-kebab}", "{module-kebab}:item"); err != nil {
+		return err
+	}
+	if err := reg.CreateActionI18n("{module-kebab}:item:manage", "Manage Items",
+		"permission.{module}.item.manage", "{module-kebab}", "{module-kebab}:item"); err != nil {
+		return err
+	}
+	return nil
+}
+
+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 {module}migrations.Migrate(db)
+}
+
+func (m *Module) Seed(_ *gorm.DB) error {
+	return nil
+}
+
+func (m *Module) ensureServices(db *gorm.DB) {
+	if m == nil || db == nil || m.items != nil {
+		return
+	}
+	repo := {module}repository.NewItemRepository(db)
+	m.items = {module}service.NewItemService(repo)
+}
+```
+
+### B2: Model
+
+```go
+package models
+
+import "github.com/robsuncn/keystone/domain/models"
+
+type ItemStatus string
+
+const (
+	StatusActive   ItemStatus = "active"
+	StatusInactive ItemStatus = "inactive"
+)
+
+func (s ItemStatus) IsValid() bool {
+	switch s {
+	case StatusActive, StatusInactive:
+		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      ItemStatus `gorm:"size:20;not null;default:'active'" json:"status"`
+}
+
+func ({Entity}) TableName() string {
+	return "{table_name}"
+}
+```
+
+### B3: Handler
+
+```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"
+
+	"{module}models" "__APP_NAME__/apps/server/internal/modules/{module}/domain/models"
+	"{module}service" "__APP_NAME__/apps/server/internal/modules/{module}/domain/service"
+	modulei18n "__APP_NAME__/apps/server/internal/modules/{module}/i18n"
+)
+
+type ItemHandler struct {
+	svc *{module}service.ItemService
+}
+
+func NewItemHandler(svc *{module}service.ItemService) *ItemHandler {
+	if svc == nil {
+		return nil
+	}
+	return &ItemHandler{svc: svc}
+}
+
+type itemInput struct {
+	Name        string                    `json:"name"`
+	Description string                    `json:"description"`
+	Status      {module}models.ItemStatus `json:"status"`
+}
+
+type itemUpdateInput struct {
+	Name        *string                    `json:"name"`
+	Description *string                    `json:"description"`
+	Status      *{module}models.ItemStatus `json:"status"`
+}
+
+const defaultTenantID uint = 1
+
+func resolveTenantID(c *gin.Context) uint {
+	if c == nil {
+		return defaultTenantID
+	}
+	if tenantID, ok := hcommon.GetTenantID(c); ok && tenantID > 0 {
+		return tenantID
+	}
+	return defaultTenantID
+}
+
+func (h *ItemHandler) 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.MsgItemLoadFailed)
+		return
+	}
+	response.Success(c, gin.H{"items": items})
+}
+
+func (h *ItemHandler) Create(c *gin.Context) {
+	if h == nil || h.svc == nil {
+		response.ServiceUnavailableI18n(c, modulei18n.MsgServiceUnavailable)
+		return
+	}
+	tenantID := resolveTenantID(c)
+	var input itemInput
+	if err := c.ShouldBindJSON(&input); err != nil {
+		response.BadRequestI18n(c, modulei18n.MsgInvalidPayload)
+		return
+	}
+	item, err := h.svc.Create(c.Request.Context(), tenantID, {module}service.ItemInput{
+		Name:        input.Name,
+		Description: input.Description,
+		Status:      input.Status,
+	})
+	if err != nil {
+		handleServiceError(c, err)
+		return
+	}
+	response.CreatedI18n(c, modulei18n.MsgItemCreated, item)
+}
+
+func (h *ItemHandler) 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 itemUpdateInput
+	if err := c.ShouldBindJSON(&input); err != nil {
+		response.BadRequestI18n(c, modulei18n.MsgInvalidPayload)
+		return
+	}
+	item, err := h.svc.Update(c.Request.Context(), tenantID, id, {module}service.ItemUpdateInput{
+		Name:        input.Name,
+		Description: input.Description,
+		Status:      input.Status,
+	})
+	if err != nil {
+		handleServiceError(c, err)
+		return
+	}
+	response.SuccessI18n(c, modulei18n.MsgItemUpdated, item)
+}
+
+func (h *ItemHandler) 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 {
+		handleServiceError(c, err)
+		return
+	}
+	response.SuccessI18n(c, modulei18n.MsgItemDeleted, gin.H{"id": id})
+}
+
+func handleServiceError(c *gin.Context, err error) {
+	var i18nErr *i18n.I18nError
+	if errors.As(err, &i18nErr) {
+		if i18nErr.Key == modulei18n.MsgItemNotFound {
+			response.NotFoundI18n(c, i18nErr.Key)
+		} else {
+			response.BadRequestI18n(c, i18nErr.Key)
+		}
+		return
+	}
+	response.InternalErrorI18n(c, modulei18n.MsgItemUpdateFailed)
+}
+```
+
+### B4: Service
+
+```go
+package service
+
+import (
+	"context"
+	"strings"
+
+	"{module}models" "__APP_NAME__/apps/server/internal/modules/{module}/domain/models"
+)
+
+type ItemRepository interface {
+	List(ctx context.Context, tenantID uint) ([]{module}models.{Entity}, error)
+	FindByID(tenantID, id uint) (*{module}models.{Entity}, error)
+	Create(ctx context.Context, item *{module}models.{Entity}) error
+	Update(ctx context.Context, item *{module}models.{Entity}) error
+	Delete(ctx context.Context, item *{module}models.{Entity}) error
+}
+
+type ItemService struct {
+	repo ItemRepository
+}
+
+type ItemInput struct {
+	Name        string
+	Description string
+	Status      {module}models.ItemStatus
+}
+
+type ItemUpdateInput struct {
+	Name        *string
+	Description *string
+	Status      *{module}models.ItemStatus
+}
+
+func NewItemService(repo ItemRepository) *ItemService {
+	return &ItemService{repo: repo}
+}
+
+func (s *ItemService) List(ctx context.Context, tenantID uint) ([]{module}models.{Entity}, error) {
+	return s.repo.List(ctx, tenantID)
+}
+
+func (s *ItemService) Create(ctx context.Context, tenantID uint, input ItemInput) (*{module}models.{Entity}, error) {
+	name := strings.TrimSpace(input.Name)
+	if name == "" {
+		return nil, ErrNameRequired
+	}
+	status := input.Status
+	if status == "" {
+		status = {module}models.StatusActive
+	}
+	if !status.IsValid() {
+		return nil, ErrStatusInvalid
+	}
+	item := &{module}models.{Entity}{
+		Name:        name,
+		Description: strings.TrimSpace(input.Description),
+		Status:      status,
+	}
+	item.TenantID = tenantID
+	if err := s.repo.Create(ctx, item); err != nil {
+		return nil, err
+	}
+	return item, nil
+}
+
+func (s *ItemService) Update(ctx context.Context, tenantID, id uint, input ItemUpdateInput) (*{module}models.{Entity}, error) {
+	item, 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
+		}
+		item.Name = name
+	}
+	if input.Description != nil {
+		item.Description = strings.TrimSpace(*input.Description)
+	}
+	if input.Status != nil {
+		if !input.Status.IsValid() {
+			return nil, ErrStatusInvalid
+		}
+		item.Status = *input.Status
+	}
+	if err := s.repo.Update(ctx, item); err != nil {
+		return nil, err
+	}
+	return item, nil
+}
+
+func (s *ItemService) Delete(ctx context.Context, tenantID, id uint) error {
+	item, err := s.repo.FindByID(tenantID, id)
+	if err != nil {
+		return err
+	}
+	return s.repo.Delete(ctx, item)
+}
+```
+
+### B5: Errors
+
+```go
+package service
+
+import (
+	"github.com/robsuncn/keystone/infra/i18n"
+	modulei18n "__APP_NAME__/apps/server/internal/modules/{module}/i18n"
+)
+
+var (
+	ErrItemNotFound  = &i18n.I18nError{Key: modulei18n.MsgItemNotFound}
+	ErrNameRequired  = &i18n.I18nError{Key: modulei18n.MsgNameRequired}
+	ErrStatusInvalid = &i18n.I18nError{Key: modulei18n.MsgStatusInvalid}
+)
+```
+
+### B6: Repository
+
+```go
+package repository
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	"{module}models" "__APP_NAME__/apps/server/internal/modules/{module}/domain/models"
+	"{module}service" "__APP_NAME__/apps/server/internal/modules/{module}/domain/service"
+)
+
+type ItemRepository struct {
+	db *gorm.DB
+}
+
+func NewItemRepository(db *gorm.DB) *ItemRepository {
+	return &ItemRepository{db: db}
+}
+
+func (r *ItemRepository) List(ctx context.Context, tenantID uint) ([]{module}models.{Entity}, error) {
+	var items []{module}models.{Entity}
+	err := r.db.WithContext(ctx).
+		Where("tenant_id = ?", tenantID).
+		Order("created_at desc").
+		Find(&items).Error
+	return items, err
+}
+
+func (r *ItemRepository) FindByID(tenantID, id uint) (*{module}models.{Entity}, error) {
+	var item {module}models.{Entity}
+	err := r.db.Where("tenant_id = ? AND id = ?", tenantID, id).First(&item).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, {module}service.ErrItemNotFound
+	}
+	return &item, err
+}
+
+func (r *ItemRepository) Create(ctx context.Context, item *{module}models.{Entity}) error {
+	return r.db.WithContext(ctx).Create(item).Error
+}
+
+func (r *ItemRepository) Update(ctx context.Context, item *{module}models.{Entity}) error {
+	return r.db.WithContext(ctx).Save(item).Error
+}
+
+func (r *ItemRepository) Delete(ctx context.Context, item *{module}models.{Entity}) error {
+	return r.db.WithContext(ctx).Delete(item).Error
+}
+```
+
+### B7: i18n Keys
+
+```go
+package {module}i18n
+
+const (
+	MsgItemCreated      = "{module-kebab}.item.created"
+	MsgItemUpdated      = "{module-kebab}.item.updated"
+	MsgItemDeleted      = "{module-kebab}.item.deleted"
+	MsgItemNotFound     = "{module-kebab}.item.notFound"
+	MsgItemLoadFailed   = "{module-kebab}.item.loadFailed"
+	MsgItemCreateFailed = "{module-kebab}.item.createFailed"
+	MsgItemUpdateFailed = "{module-kebab}.item.updateFailed"
+	MsgItemDeleteFailed = "{module-kebab}.item.deleteFailed"
+	MsgNameRequired     = "{module-kebab}.validation.nameRequired"
+	MsgStatusInvalid    = "{module-kebab}.validation.statusInvalid"
+	MsgInvalidID        = "{module-kebab}.validation.invalidId"
+	MsgInvalidPayload   = "{module-kebab}.validation.invalidPayload"
+	MsgServiceUnavailable = "{module-kebab}.service.unavailable"
+)
+```
+
+### B8: i18n Registration
+
+```go
+package {module}i18n
+
+import (
+	"embed"
+	"github.com/robsuncn/keystone/infra/i18n"
+)
+
+//go:embed locales/*.json
+var localeFS embed.FS
+
+func RegisterLocales() error {
+	return i18n.LoadModuleLocales(localeFS, "locales")
+}
+```
+
+### B9: i18n Locales
+
+**zh-CN.json:**
+```json
+{
+  "{module-kebab}.item.created": "创建成功",
+  "{module-kebab}.item.updated": "更新成功",
+  "{module-kebab}.item.deleted": "删除成功",
+  "{module-kebab}.item.notFound": "记录不存在",
+  "{module-kebab}.item.loadFailed": "加载失败",
+  "{module-kebab}.validation.nameRequired": "名称不能为空",
+  "{module-kebab}.validation.statusInvalid": "状态值无效",
+  "{module-kebab}.validation.invalidId": "无效的 ID",
+  "{module-kebab}.validation.invalidPayload": "请求参数无效",
+  "{module-kebab}.service.unavailable": "服务暂不可用",
+  "permission.{module}.item": "{Entity}管理",
+  "permission.{module}.item.view": "查看{Entity}",
+  "permission.{module}.item.manage": "管理{Entity}"
+}
+```
+
+**en-US.json:**
+```json
+{
+  "{module-kebab}.item.created": "Created successfully",
+  "{module-kebab}.item.updated": "Updated successfully",
+  "{module-kebab}.item.deleted": "Deleted successfully",
+  "{module-kebab}.item.notFound": "Record not found",
+  "{module-kebab}.item.loadFailed": "Failed to load",
+  "{module-kebab}.validation.nameRequired": "Name is required",
+  "{module-kebab}.validation.statusInvalid": "Invalid status value",
+  "{module-kebab}.validation.invalidId": "Invalid ID",
+  "{module-kebab}.validation.invalidPayload": "Invalid request payload",
+  "{module-kebab}.service.unavailable": "Service unavailable",
+  "permission.{module}.item": "{Entity} Items",
+  "permission.{module}.item.view": "View {Entity}",
+  "permission.{module}.item.manage": "Manage {Entity}"
+}
+```
+
+---
+
+## 四、前端模式
+
+### F1: 模块入口
+
+```typescript
+import { registerModule, loadModuleLocales } from '@robsun/keystone-web-core'
+import { {module}Routes } from './routes'
+
+loadModuleLocales('{module}', {
+  'zh-CN': () => import('./locales/zh-CN/{module}.json'),
+  'en-US': () => import('./locales/en-US/{module}.json'),
+})
+
+registerModule({ name: '{module}', routes: {module}Routes })
+```
+
+### F2: 路由配置
+
+```typescript
+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}ItemsPage = lazyNamed(() => import('./pages/{Entity}ItemsPage'), '{Entity}ItemsPage')
+
+export const {module}Routes: RouteObject[] = [
+  {
+    path: '{module-kebab}',
+    element: <{Entity}ItemsPage />,
+    handle: {
+      menu: {
+        labelKey: '{module}:menu.items',
+        icon: <AppstoreOutlined />,
+        permission: '{module-kebab}:item:view',
+      },
+      breadcrumbKey: '{module}:menu.items',
+      permission: '{module-kebab}:item:view',
+    },
+  },
+].map((route) => ({
+  ...route,
+  element: route.element ? withSuspense(route.element) : route.element,
+}))
+```
+
+### F3: 类型定义
+
+```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
+}
+
+export interface Create{Entity}Input {
+  name: string
+  description?: string
+  status?: {Entity}Status
+}
+
+export interface Update{Entity}Input {
+  name?: string
+  description?: string
+  status?: {Entity}Status
+}
+```
+
+### F4: API 服务
+
+```typescript
+import { api, type ApiResponse } from '@robsun/keystone-web-core'
+import type { {Entity}, Create{Entity}Input, Update{Entity}Input } from '../types'
+
+type ListResponse = { items: {Entity}[] }
+
+export const list{Entity}Items = async () => {
+  const { data } = await api.get<ApiResponse<ListResponse>>('/{module-kebab}/items')
+  return data.data.items
+}
+
+export const create{Entity}Item = async (payload: Create{Entity}Input) => {
+  const { data } = await api.post<ApiResponse<{Entity}>>('/{module-kebab}/items', payload)
+  return data.data
+}
+
+export const update{Entity}Item = async (id: number, payload: Update{Entity}Input) => {
+  const { data } = await api.patch<ApiResponse<{Entity}>>(`/{module-kebab}/items/${id}`, payload)
+  return data.data
+}
+
+export const delete{Entity}Item = async (id: number) => {
+  await api.delete<ApiResponse<void>>(`/{module-kebab}/items/${id}`)
+}
+```
+
+### F5: 列表页面
+
+```typescript
+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 '@robsun/keystone-web-core'
+import dayjs from 'dayjs'
+import { create{Entity}Item, delete{Entity}Item, list{Entity}Items, update{Entity}Item } 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}ItemsPage() {
+  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 {
+      setItems(await list{Entity}Items())
+    } catch (err) {
+      message.error(err instanceof Error ? err.message : t('messages.loadFailed'))
+    } finally {
+      setLoading(false)
+    }
+  }, [message, t])
+
+  // 初始加载只执行一次
+  useEffect(() => {
+    void fetchItems()
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  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}Item(editingItem.id, payload)
+        message.success(t('messages.updateSuccess'))
+      } else {
+        await create{Entity}Item(payload)
+        message.success(t('messages.createSuccess'))
+      }
+      closeModal()
+      await fetchItems()
+    } catch (err) {
+      message.error(err instanceof Error ? err.message : tc('messages.operationFailed'))
+    } finally {
+      setSaving(false)
+    }
+  }, [closeModal, editingItem, fetchItems, form, message, t, tc])
+
+  const handleDelete = useCallback(async (id: number) => {
+    try {
+      await delete{Entity}Item(id)
+      await fetchItems()
+      message.success(t('messages.deleteSuccess'))
+    } catch (err) {
+      message.error(err instanceof Error ? err.message : tc('messages.operationFailed'))
+    }
+  }, [fetchItems, message, t, tc])
+
+  const columns: ColumnsType<{Entity}> = useMemo(() => [
+    { title: t('fields.name'), dataIndex: 'name', key: 'name' },
+    { title: t('fields.description'), dataIndex: 'description', key: 'description',
+      render: (v: string) => v ? <Typography.Text type="secondary">{v}</Typography.Text> : '-' },
+    { title: t('fields.status'), dataIndex: 'status', key: 'status',
+      render: (v: {Entity}Status) => <Tag color={statusColors[v]}>{t(`status.${v}`)}</Tag> },
+    { title: tc('table.updatedAt'), dataIndex: 'updated_at', key: 'updated_at',
+      render: (v: string) => v ? dayjs(v).format('YYYY-MM-DD HH:mm') : '-' },
+    { title: tc('table.actions'), key: 'actions',
+      render: (_, r) => (
+        <Space>
+          <Button type="link" onClick={() => openEdit(r)}>{tc('actions.edit')}</Button>
+          <Popconfirm title={tc('confirm.deleteContent')} onConfirm={() => handleDelete(r.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('fields.status')} name="status" rules={[{ required: true, message: tc('form.required') }]}>
+            <Select options={statusOptions} />
+          </Form.Item>
+        </Form>
+      </Modal>
+    </Card>
+  )
+}
+```
+
+### F6: i18n Locales
+
+**zh-CN/{module}.json:**
+```json
+{
+  "menu": { "items": "{Entity}管理" },
+  "page": { "title": "{Entity}列表", "createButton": "新建" },
+  "fields": { "name": "名称", "description": "描述", "status": "状态" },
+  "form": { "nameLabel": "名称", "namePlaceholder": "请输入名称", "descriptionLabel": "描述", "descriptionPlaceholder": "请输入描述" },
+  "messages": { "createSuccess": "创建成功", "updateSuccess": "更新成功", "deleteSuccess": "删除成功", "loadFailed": "加载失败" },
+  "status": { "active": "启用", "inactive": "停用" }
+}
+```
+
+**en-US/{module}.json:**
+```json
+{
+  "menu": { "items": "{Entity} Items" },
+  "page": { "title": "{Entity} List", "createButton": "Create" },
+  "fields": { "name": "Name", "description": "Description", "status": "Status" },
+  "form": { "nameLabel": "Name", "namePlaceholder": "Enter name", "descriptionLabel": "Description", "descriptionPlaceholder": "Enter description" },
+  "messages": { "createSuccess": "Created successfully", "updateSuccess": "Updated successfully", "deleteSuccess": "Deleted successfully", "loadFailed": "Failed to load" },
+  "status": { "active": "Active", "inactive": "Inactive" }
+}
+```
+
+---
+
+## 五、模块注册
+
+**后端 manifest.go:**
+```go
+import {module} "internal/modules/{module}"
+
+func RegisterModules() []core.Module {
+    return []core.Module{
+        {module}.NewModule(),
+    }
+}
+```
+
+**后端 config.yaml:**
+```yaml
+modules:
+  enabled:
+    - {module}
+```
+
+**前端 main.tsx:**
+```typescript
+import './modules/{module}'
+```
+
+---
+
+## 六、高级模式
+
+### 事务处理
+
+```go
+func (s *Service) CreateWithDetails(ctx context.Context, input Input) error {
+    return s.db.Transaction(func(tx *gorm.DB) error {
+        master := &Master{Name: input.Name}
+        if err := tx.Create(master).Error; err != nil {
+            return err
+        }
+        for _, d := range input.Details {
+            detail := &Detail{MasterID: master.ID, Value: d.Value}
+            if err := tx.Create(detail).Error; err != nil {
+                return err
+            }
+        }
+        return nil
+    })
+}
+```
+
+### 审批流集成
+
+**Model 扩展：**
+```go
+type Entity struct {
+    models.BaseModel
+    Name               string        `json:"name"`
+    Status             EntityStatus  `json:"status"`  // draft, pending, approved, rejected
+    ApprovalInstanceID *uint         `json:"approval_instance_id"`
+    RejectReason       string        `json:"reject_reason"`
+}
+```
+
+**Service 提交审批：**
+```go
+func (s *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.StatusDraft {
+        return ErrCannotSubmit
+    }
+    instance, err := s.approval.CreateInstance(ctx, approval.CreateInstanceInput{
+        TenantID:     tenantID,
+        BusinessType: ApprovalBusinessType,
+        BusinessID:   id,
+        ApplicantID:  userID,
+        Context:      map[string]interface{}{"name": entity.Name},
+    })
+    if err != nil {
+        return err
+    }
+    entity.Status = models.StatusPending
+    entity.ApprovalInstanceID = &instance.ID
+    return s.repo.Update(ctx, entity)
+}
+```
+
+**审批回调：**
+```go
+func (c *ApprovalCallback) OnApproved(ctx context.Context, tenantID, businessID, approverID uint) error {
+    return c.repo.UpdateStatus(ctx, tenantID, businessID, models.StatusApproved)
+}
+
+func (c *ApprovalCallback) OnRejected(ctx context.Context, tenantID, businessID, approverID uint, reason string) error {
+    entity, _ := c.repo.FindByID(tenantID, businessID)
+    entity.Status = models.StatusRejected
+    entity.RejectReason = reason
+    return c.repo.Update(ctx, entity)
+}
+```
+
+### 数据权限
+
+```go
+func (h *Handler) List(c *gin.Context) {
+    tenantID := resolveTenantID(c)
+    userID, _ := hcommon.GetUserID(c)
+    scope := datascope.FromContext(c)
+
+    items, err := h.svc.ListWithScope(c.Request.Context(), tenantID, userID, scope)
+    if err != nil {
+        response.InternalErrorI18n(c, modulei18n.MsgListFailed)
+        return
+    }
+    response.Success(c, gin.H{"items": items})
+}
+```
+
+### 文件上传
+
+```go
+func (h *Handler) Upload(c *gin.Context) {
+    file, err := c.FormFile("file")
+    if err != nil {
+        response.BadRequestI18n(c, modulei18n.MsgInvalidFile)
+        return
+    }
+    if file.Size > 10*1024*1024 { // 10MB
+        response.BadRequestI18n(c, modulei18n.MsgFileTooLarge)
+        return
+    }
+    path, err := h.storage.Save(c.Request.Context(), file)
+    if err != nil {
+        response.InternalErrorI18n(c, modulei18n.MsgUploadFailed)
+        return
+    }
+    response.Success(c, gin.H{"path": path})
+}
+```
+
+### 分页查询
+
+```go
+import "github.com/robsuncn/keystone/infra/pagination"
+
+func (h *Handler) List(c *gin.Context) {
+    tenantID := resolveTenantID(c)
+    pageReq := pagination.ParseRequest(c)
+
+    items, total, err := h.svc.List(c.Request.Context(), tenantID, pageReq)
+    if err != nil {
+        response.InternalErrorI18n(c, modulei18n.MsgListFailed)
+        return
+    }
+    response.Success(c, pagination.NewResponse(items, total, pageReq))
+}
+```
+
+### 软删除
+
+```go
+// 查询自动排除已删除
+db.Find(&items)
+
+// 包含已删除
+db.Unscoped().Find(&items)
+
+// 恢复已删除
+db.Unscoped().Model(&entity).Update("deleted_at", nil)
+
+// 永久删除
+db.Unscoped().Delete(&entity)
+```