@robsun/create-keystone-app 0.1.17 → 0.2.0

package/README.md

@@ -8,24 +8,25 @@ pnpm dlx @robsun/create-keystone-app <dir> [options]
 
 ## 选项
 - `<dir>`：目标目录（必填），可为新目录名或 `.`（当前目录）。
-- `--profile <starter|full>`：模板档位，默认 `starter`。
-- `--demo` / `--no-demo`：是否包含 Demo 模块（`full` 默认包含）。
 - `--db <sqlite|postgres>`：数据库驱动（默认 `sqlite`）。
 - `--queue <memory|redis>`：队列驱动（默认 `memory`）。
 - `--storage <local|s3>`：存储驱动（默认 `local`）。
 
 ## 示例
 ```bash
-npx @robsun/create-keystone-app my-app --profile=full --db=postgres --queue=redis
+npx @robsun/create-keystone-app my-app --db=postgres --queue=redis --storage=s3
 ```
 
 ## 初始化后操作
 ```bash
 cd <dir>
 pnpm install
+pnpm server:dev
+pnpm web:dev
 pnpm dev
 ```
 
-## 端口与 Demo
+## 端口与 Example
 - Web 默认端口：`3000`；后端默认端口：`8080`。
-- Demo API：`/api/v1/demo/tasks`（仅在包含 Demo 时可用）。
+- Example API：`/api/v1/example/items`。
+- 权限：`example:item:view`、`example:item:manage`。

package/bin/create-keystone-app.js

@@ -6,9 +6,6 @@ const usage = [
   'Usage: create-keystone-app <dir> [options]',
   '',
   'Options:',
-  '  --profile <starter|full>  Template profile (default: starter)',
-  '  --demo                    Include demo module',
-  '  --no-demo                 Exclude demo module',
   '  --db <sqlite|postgres>    Database driver (default: sqlite)',
   '  --queue <memory|redis>    Queue driver (default: memory)',
   '  --storage <local|s3>      Storage driver (default: local)',
@@ -26,19 +23,10 @@ if (!args.target) {
   process.exit(1);
 }
 
-const profile = normalizeChoice(args.profile, ['starter', 'full'], 'profile') || 'starter';
 const db = normalizeChoice(args.db, ['sqlite', 'postgres'], 'db') || 'sqlite';
 const queue = normalizeChoice(args.queue, ['memory', 'redis'], 'queue') || 'memory';
 const storage = normalizeChoice(args.storage, ['local', 's3'], 'storage') || 'local';
 
-let includeDemo = profile === 'full';
-if (args.demo === true) {
-  includeDemo = true;
-}
-if (args.demo === false) {
-  includeDemo = false;
-}
-
 const targetDir = path.resolve(process.cwd(), args.target);
 const targetName = args.target === '.'
   ? path.basename(process.cwd())
@@ -62,15 +50,12 @@ copyDir(templateDir, targetDir, {
 
 applyConfigOptions(targetDir, { db, queue, storage });
 
-if (!includeDemo) {
-  stripDemo(targetDir);
-}
-
 console.log(`Created ${targetName}`);
 console.log('Next steps:');
 console.log(`  cd ${args.target}`);
 console.log('  pnpm install');
 console.log('  pnpm server:dev');
+console.log('  pnpm web:dev');
 console.log('  pnpm dev');
 
 function normalizePackageName(name) {
@@ -119,49 +104,6 @@ function shouldSkipDir(name) {
   return name === 'node_modules' || name === '.git';
 }
 
-function stripDemo(targetDir) {
-  removePath(path.join(targetDir, 'apps', 'web', 'src', 'modules', 'demo'));
-  removePath(path.join(targetDir, 'apps', 'server', 'internal', 'modules', 'demo'));
-
-  updateFile(path.join(targetDir, 'apps', 'web', 'src', 'main.tsx'), (content) =>
-    content.replace(/^\s*import ['"]\.\/modules\/demo['"];?\r?\n/m, '')
-  );
-  updateFile(path.join(targetDir, 'apps', 'web', 'src', 'app.config.ts'), (content) =>
-    content.replace(/,\s*['"]demo['"]/, '')
-  );
-  updateFile(path.join(targetDir, 'apps', 'server', 'config.yaml'), (content) =>
-    content.replace(/\r?\n\s*-\s*['"]demo['"]\s*/g, '')
-  );
-  updateFile(path.join(targetDir, 'apps', 'server', 'config.example.yaml'), (content) =>
-    content.replace(/\r?\n\s*-\s*['"]demo['"]\s*/g, '')
-  );
-  updateFile(path.join(targetDir, 'README.md'), (content) =>
-    content.replace(/<!-- DEMO_START -->[\s\S]*?<!-- DEMO_END -->\s*/m, '')
-  );
-
-  const manifestPath = path.join(
-    targetDir,
-    'apps',
-    'server',
-    'internal',
-    'modules',
-    'manifest.go'
-  );
-  const manifest = `package modules
-
-import (
-\texample "__APP_NAME__/apps/server/internal/modules/example"
-)
-
-// RegisterAll wires the module registry for this app.
-func RegisterAll() {
-\tClear()
-\tRegister(example.NewModule())
-}
-`;
-  fs.writeFileSync(manifestPath, manifest, 'utf8');
-}
-
 function applyConfigOptions(targetDir, options) {
   const configFiles = [
     path.join(targetDir, 'apps', 'server', 'config.yaml'),
@@ -201,12 +143,6 @@ function updateYamlSectionValue(content, section, key, value) {
   return content.replace(pattern, `$1${value}$3`);
 }
 
-function removePath(target) {
-  if (fs.existsSync(target)) {
-    fs.rmSync(target, { recursive: true, force: true });
-  }
-}
-
 function updateFile(filePath, updater) {
   if (!fs.existsSync(filePath)) {
     return;
@@ -227,28 +163,14 @@ function shouldMakeExecutable(filePath) {
 }
 
 function parseArgs(argv) {
-  const out = { demo: null };
+  const out = {};
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    if (arg === '--demo') {
-      out.demo = true;
-      continue;
-    }
-    if (arg === '--no-demo') {
-      out.demo = false;
-      continue;
-    }
     if (arg === '--help' || arg === '-h') {
       out.help = true;
       continue;
     }
 
-    const profile = readValueOption(arg, argv, i, '--profile');
-    if (profile) {
-      out.profile = profile.value;
-      i += profile.skip;
-      continue;
-    }
     const db = readValueOption(arg, argv, i, '--db');
     if (db) {
       out.db = db.value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robsun/create-keystone-app",
-  "version": "0.1.17",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },

package/template/README.md

@@ -23,7 +23,7 @@ pnpm web:dev
 - 复制 `apps/web/.env.example` 为 `apps/web/.env`（Vite 会读取）。
 - 检查 `apps/server/config.yaml`（Go 运行配置）。
 - 需要外部依赖时参考 `docker-compose.yml`。
-- 建议阅读：`docs/CONVENTIONS.md`、`docs/CODE_STYLE.md`、`apps/web/README.md`、`apps/server/README.md`。
+- 建议阅读：`docs/GETTING_STARTED.md`、`docs/CONVENTIONS.md`、`docs/CODE_STYLE.md`、`apps/web/README.md`、`apps/server/README.md`。
 
 ## 常用命令
 - `pnpm dev`：跨平台开发启动（Air + Vite）。
@@ -50,18 +50,10 @@ pnpm web:dev
 ```
 
 ## Example 模块（默认）
-Starter 与 Full 模式默认包含 Example 模块，用于展示模块注册、权限、路由与 API。
-- 菜单：Example
-- API：`/api/v1/example/hello`
-- 权限：`example:view`
-
-<!-- DEMO_START -->
-## Demo 模块（可选）
-如果需要 Demo，可在创建时使用 `--demo` 或 `--profile=full`。
-- 菜单：Demo Tasks
-- API：`/api/v1/demo/tasks`
-- 权限：`demo:task:view`、`demo:task:manage`
-<!-- DEMO_END -->
+Example 模块展示完整的 CRUD 模式、权限命名与 DDD 分层结构。
+- 菜单：Example Items
+- API：`/api/v1/example/items`
+- 权限：`example:item:view`、`example:item:manage`
 
 ## 默认登录
 - Tenant code: `default`

package/template/apps/server/config.example.yaml

@@ -7,7 +7,6 @@ modules:
   enabled:
     - "keystone"
     - "example"
-    - "demo"
 
 database:
   driver: "sqlite"

package/template/apps/server/config.yaml

@@ -7,7 +7,6 @@ modules:
   enabled:
     - "keystone"
     - "example"
-    - "demo"
 
 database:
   driver: "sqlite"

package/template/apps/server/internal/modules/example/api/handler/item_handler.go

@@ -0,0 +1,162 @@
+package handler
+
+import (
+	"errors"
+
+	"github.com/gin-gonic/gin"
+	hcommon "github.com/robsuncn/keystone/api/handler/common"
+	"github.com/robsuncn/keystone/api/response"
+
+	"__APP_NAME__/apps/server/internal/modules/example/domain/models"
+	"__APP_NAME__/apps/server/internal/modules/example/domain/service"
+)
+
+type ItemHandler struct {
+	items *service.ItemService
+}
+
+func NewItemHandler(items *service.ItemService) *ItemHandler {
+	if items == nil {
+		return nil
+	}
+	return &ItemHandler{items: items}
+}
+
+type itemInput struct {
+	Title       string            `json:"title"`
+	Description string            `json:"description"`
+	Status      models.ItemStatus `json:"status"`
+}
+
+type itemUpdateInput struct {
+	Title       *string            `json:"title"`
+	Description *string            `json:"description"`
+	Status      *models.ItemStatus `json:"status"`
+}
+
+const defaultTenantID uint = 1
+
+func (h *ItemHandler) List(c *gin.Context) {
+	if h == nil || h.items == nil {
+		response.ServiceUnavailable(c, "example items unavailable")
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	items, err := h.items.List(c.Request.Context(), tenantID)
+	if err != nil {
+		response.InternalError(c, "failed to load example items")
+		return
+	}
+
+	response.Success(c, gin.H{"items": items})
+}
+
+func (h *ItemHandler) Create(c *gin.Context) {
+	if h == nil || h.items == nil {
+		response.ServiceUnavailable(c, "example items unavailable")
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	var input itemInput
+	if err := c.ShouldBindJSON(&input); err != nil {
+		response.BadRequest(c, "invalid payload")
+		return
+	}
+
+	item, err := h.items.Create(c.Request.Context(), tenantID, service.ItemInput{
+		Title:       input.Title,
+		Description: input.Description,
+		Status:      input.Status,
+	})
+	if err != nil {
+		switch {
+		case errors.Is(err, service.ErrTitleRequired):
+			response.BadRequest(c, "title is required")
+		case errors.Is(err, service.ErrStatusInvalid):
+			response.BadRequest(c, "invalid status")
+		default:
+			response.InternalError(c, "failed to create example item")
+		}
+		return
+	}
+
+	response.Created(c, item)
+}
+
+func (h *ItemHandler) Update(c *gin.Context) {
+	if h == nil || h.items == nil {
+		response.ServiceUnavailable(c, "example items unavailable")
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	id, err := hcommon.ParseUintParam(c, "id")
+	if err != nil || id == 0 {
+		response.BadRequest(c, "invalid id")
+		return
+	}
+
+	var input itemUpdateInput
+	if err := c.ShouldBindJSON(&input); err != nil {
+		response.BadRequest(c, "invalid payload")
+		return
+	}
+
+	item, err := h.items.Update(c.Request.Context(), tenantID, id, service.ItemUpdateInput{
+		Title:       input.Title,
+		Description: input.Description,
+		Status:      input.Status,
+	})
+	if err != nil {
+		switch {
+		case errors.Is(err, service.ErrItemNotFound):
+			response.NotFound(c, "item not found")
+		case errors.Is(err, service.ErrTitleRequired):
+			response.BadRequest(c, "title is required")
+		case errors.Is(err, service.ErrStatusInvalid):
+			response.BadRequest(c, "invalid status")
+		default:
+			response.InternalError(c, "failed to update example item")
+		}
+		return
+	}
+
+	response.SuccessWithMessage(c, "updated", item)
+}
+
+func (h *ItemHandler) Delete(c *gin.Context) {
+	if h == nil || h.items == nil {
+		response.ServiceUnavailable(c, "example items unavailable")
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	id, err := hcommon.ParseUintParam(c, "id")
+	if err != nil || id == 0 {
+		response.BadRequest(c, "invalid id")
+		return
+	}
+
+	if err := h.items.Delete(c.Request.Context(), tenantID, id); err != nil {
+		if errors.Is(err, service.ErrItemNotFound) {
+			response.NotFound(c, "item not found")
+			return
+		}
+		response.InternalError(c, "failed to delete example item")
+		return
+	}
+
+	response.SuccessWithMessage(c, "deleted", 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
+}

package/template/apps/server/internal/modules/example/bootstrap/migrations/item.go

@@ -0,0 +1,21 @@
+package migrations
+
+import (
+	"fmt"
+	"log"
+
+	"gorm.io/gorm"
+
+	"__APP_NAME__/apps/server/internal/modules/example/domain/models"
+)
+
+func Migrate(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+	log.Println("[example] Running migrations...")
+	if err := db.AutoMigrate(&models.ExampleItem{}); err != nil {
+		return fmt.Errorf("auto migrate example_items: %w", err)
+	}
+	return nil
+}

package/template/apps/server/internal/modules/example/bootstrap/seeds/item.go

@@ -0,0 +1,33 @@
+package seeds
+
+import (
+	"log"
+
+	"gorm.io/gorm"
+
+	"__APP_NAME__/apps/server/internal/modules/example/domain/models"
+)
+
+func Seed(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+
+	var count int64
+	if err := db.Model(&models.ExampleItem{}).Count(&count).Error; err != nil {
+		return err
+	}
+	if count > 0 {
+		return nil
+	}
+
+	log.Println("[example] Seeding initial data...")
+	items := []models.ExampleItem{
+		{Title: "First example item", Description: "A seeded record to explore CRUD.", Status: models.StatusActive},
+		{Title: "Inactive example item", Description: "Use status to drive UI state.", Status: models.StatusInactive},
+	}
+	for i := range items {
+		items[i].TenantID = 1
+	}
+	return db.Create(&items).Error
+}

package/template/apps/server/internal/modules/example/domain/models/item.go

@@ -0,0 +1,30 @@
+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 ExampleItem struct {
+	models.BaseModel
+	Title       string     `gorm:"size:200;not null" json:"title"`
+	Description string     `gorm:"size:1000" json:"description"`
+	Status      ItemStatus `gorm:"size:20;not null;default:'active'" json:"status"`
+}
+
+func (ExampleItem) TableName() string {
+	return "example_items"
+}

package/template/apps/server/internal/modules/{demo → example}/domain/service/errors.go

@@ -3,7 +3,7 @@ package service
 import "errors"
 
 var (
-	ErrTaskNotFound  = errors.New("task not found")
+	ErrItemNotFound  = errors.New("item not found")
 	ErrTitleRequired = errors.New("title is required")
 	ErrStatusInvalid = errors.New("status is invalid")
 )

package/template/apps/server/internal/modules/example/domain/service/item_service.go

@@ -0,0 +1,110 @@
+package service
+
+import (
+	"context"
+	"strings"
+
+	"__APP_NAME__/apps/server/internal/modules/example/domain/models"
+)
+
+type ItemRepository interface {
+	List(ctx context.Context, tenantID uint) ([]models.ExampleItem, error)
+	FindByID(tenantID, id uint) (*models.ExampleItem, error)
+	Create(ctx context.Context, item *models.ExampleItem) error
+	Update(ctx context.Context, item *models.ExampleItem) error
+	Delete(ctx context.Context, item *models.ExampleItem) error
+}
+
+type ItemService struct {
+	items ItemRepository
+}
+
+type ItemInput struct {
+	Title       string
+	Description string
+	Status      models.ItemStatus
+}
+
+type ItemUpdateInput struct {
+	Title       *string
+	Description *string
+	Status      *models.ItemStatus
+}
+
+func NewItemService(items ItemRepository) *ItemService {
+	return &ItemService{items: items}
+}
+
+func (s *ItemService) List(ctx context.Context, tenantID uint) ([]models.ExampleItem, error) {
+	return s.items.List(ctx, tenantID)
+}
+
+func (s *ItemService) Create(ctx context.Context, tenantID uint, input ItemInput) (*models.ExampleItem, error) {
+	title := strings.TrimSpace(input.Title)
+	if title == "" {
+		return nil, ErrTitleRequired
+	}
+
+	status := input.Status
+	if status == "" {
+		status = models.StatusActive
+	}
+	if !status.IsValid() {
+		return nil, ErrStatusInvalid
+	}
+
+	item := &models.ExampleItem{
+		Title:       title,
+		Description: strings.TrimSpace(input.Description),
+		Status:      status,
+	}
+	item.TenantID = tenantID
+
+	if err := s.items.Create(ctx, item); err != nil {
+		return nil, err
+	}
+	return item, nil
+}
+
+func (s *ItemService) Update(
+	ctx context.Context,
+	tenantID, id uint,
+	input ItemUpdateInput,
+) (*models.ExampleItem, error) {
+	item, err := s.items.FindByID(tenantID, id)
+	if err != nil {
+		return nil, err
+	}
+
+	if input.Title != nil {
+		title := strings.TrimSpace(*input.Title)
+		if title == "" {
+			return nil, ErrTitleRequired
+		}
+		item.Title = title
+	}
+
+	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.items.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.items.FindByID(tenantID, id)
+	if err != nil {
+		return err
+	}
+	return s.items.Delete(ctx, item)
+}

package/template/apps/server/internal/modules/example/infra/repository/item_repository.go

@@ -0,0 +1,49 @@
+package repository
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	"__APP_NAME__/apps/server/internal/modules/example/domain/models"
+	"__APP_NAME__/apps/server/internal/modules/example/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) ([]models.ExampleItem, error) {
+	var items []models.ExampleItem
+	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) (*models.ExampleItem, error) {
+	var item models.ExampleItem
+	err := r.db.Where("tenant_id = ? AND id = ?", tenantID, id).First(&item).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, service.ErrItemNotFound
+	}
+	return &item, err
+}
+
+func (r *ItemRepository) Create(ctx context.Context, item *models.ExampleItem) error {
+	return r.db.WithContext(ctx).Create(item).Error
+}
+
+func (r *ItemRepository) Update(ctx context.Context, item *models.ExampleItem) error {
+	return r.db.WithContext(ctx).Save(item).Error
+}
+
+func (r *ItemRepository) Delete(ctx context.Context, item *models.ExampleItem) error {
+	return r.db.WithContext(ctx).Delete(item).Error
+}