@robsun/create-keystone-app 0.1.14 → 0.1.16

package/bin/create-keystone-app.js

@@ -87,6 +87,9 @@ function copyDir(src, dest, replacements) {
   fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });
   for (const entry of entries) {
+    if (entry.isDirectory() && shouldSkipDir(entry.name)) {
+      continue;
+    }
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
     if (entry.isDirectory()) {
@@ -112,6 +115,10 @@ function copyFile(src, dest, replacements) {
   }
 }
 
+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'));
@@ -142,9 +149,14 @@ function stripDemo(targetDir) {
   );
   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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robsun/create-keystone-app",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "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`、`apps/web/README.md`、`apps/server/README.md`。
+- 建议阅读：`docs/CONVENTIONS.md`、`docs/CODE_STYLE.md`、`apps/web/README.md`、`apps/server/README.md`。
 
 ## 常用命令
 - `pnpm dev`：跨平台开发启动（Air + Vite）。
@@ -49,6 +49,12 @@ pnpm web:dev
 └─ scripts/           # 跨平台脚本
 ```
 
+## Example 模块（默认）
+Starter 与 Full 模式默认包含 Example 模块，用于展示模块注册、权限、路由与 API。
+- 菜单：Example
+- API：`/api/v1/example/hello`
+- 权限：`example:view`
+
 <!-- DEMO_START -->
 ## Demo 模块（可选）
 如果需要 Demo，可在创建时使用 `--demo` 或 `--profile=full`。

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

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

package/template/apps/server/config.yaml

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

package/template/apps/server/internal/modules/demo/api/handler/task_handler.go

@@ -0,0 +1,152 @@
+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/demo/domain/models"
+	"__APP_NAME__/apps/server/internal/modules/demo/domain/service"
+)
+
+type TaskHandler struct {
+	tasks *service.TaskService
+}
+
+func NewTaskHandler(tasks *service.TaskService) *TaskHandler {
+	if tasks == nil {
+		return nil
+	}
+	return &TaskHandler{tasks: tasks}
+}
+
+type taskInput struct {
+	Title  string            `json:"title"`
+	Status models.TaskStatus `json:"status"`
+}
+
+const defaultTenantID uint = 1
+
+func (h *TaskHandler) List(c *gin.Context) {
+	if h == nil || h.tasks == nil {
+		response.ServiceUnavailable(c, "demo tasks unavailable")
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	items, err := h.tasks.List(c.Request.Context(), tenantID)
+	if err != nil {
+		response.InternalError(c, "failed to load demo tasks")
+		return
+	}
+
+	response.Success(c, gin.H{"items": items})
+}
+
+func (h *TaskHandler) Create(c *gin.Context) {
+	if h == nil || h.tasks == nil {
+		response.ServiceUnavailable(c, "demo tasks unavailable")
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	var input taskInput
+	if err := c.ShouldBindJSON(&input); err != nil {
+		response.BadRequest(c, "invalid payload")
+		return
+	}
+
+	task, err := h.tasks.Create(c.Request.Context(), tenantID, service.TaskInput{
+		Title:  input.Title,
+		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 demo task")
+		}
+		return
+	}
+
+	response.Created(c, task)
+}
+
+func (h *TaskHandler) Update(c *gin.Context) {
+	if h == nil || h.tasks == nil {
+		response.ServiceUnavailable(c, "demo tasks unavailable")
+		return
+	}
+	tenantID := resolveTenantID(c)
+
+	id, err := hcommon.ParseUintParam(c, "id")
+	if err != nil || id == 0 {
+		response.BadRequest(c, "invalid id")
+		return
+	}
+
+	var input taskInput
+	if err := c.ShouldBindJSON(&input); err != nil {
+		response.BadRequest(c, "invalid payload")
+		return
+	}
+
+	task, err := h.tasks.Update(c.Request.Context(), tenantID, id, service.TaskUpdateInput{
+		Title:  input.Title,
+		Status: input.Status,
+	})
+	if err != nil {
+		switch {
+		case errors.Is(err, service.ErrTaskNotFound):
+			response.NotFound(c, "task not found")
+		case errors.Is(err, service.ErrStatusInvalid):
+			response.BadRequest(c, "invalid status")
+		default:
+			response.InternalError(c, "failed to update demo task")
+		}
+		return
+	}
+
+	response.SuccessWithMessage(c, "updated", task)
+}
+
+func (h *TaskHandler) Delete(c *gin.Context) {
+	if h == nil || h.tasks == nil {
+		response.ServiceUnavailable(c, "demo tasks 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.tasks.Delete(c.Request.Context(), tenantID, id); err != nil {
+		if errors.Is(err, service.ErrTaskNotFound) {
+			response.NotFound(c, "task not found")
+			return
+		}
+		response.InternalError(c, "failed to delete demo task")
+		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/demo/bootstrap/migrations/task.go

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

package/template/apps/server/internal/modules/demo/bootstrap/seeds/task.go

@@ -0,0 +1,33 @@
+package seeds
+
+import (
+	"log"
+
+	"gorm.io/gorm"
+
+	"__APP_NAME__/apps/server/internal/modules/demo/domain/models"
+)
+
+func Seed(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+
+	var count int64
+	if err := db.Model(&models.DemoTask{}).Count(&count).Error; err != nil {
+		return err
+	}
+	if count > 0 {
+		return nil
+	}
+
+	log.Println("[demo] Seeding initial data...")
+	tasks := []models.DemoTask{
+		{Title: "Set up project", Status: models.StatusTodo},
+		{Title: "Review UI states", Status: models.StatusDone},
+	}
+	for i := range tasks {
+		tasks[i].TenantID = 1
+	}
+	return db.Create(&tasks).Error
+}

package/template/apps/server/internal/modules/demo/domain/models/task.go

@@ -0,0 +1,30 @@
+package models
+
+import "github.com/robsuncn/keystone/domain/models"
+
+type TaskStatus string
+
+const (
+	StatusTodo       TaskStatus = "todo"
+	StatusInProgress TaskStatus = "in_progress"
+	StatusDone       TaskStatus = "done"
+)
+
+func (s TaskStatus) IsValid() bool {
+	switch s {
+	case StatusTodo, StatusInProgress, StatusDone:
+		return true
+	default:
+		return false
+	}
+}
+
+type DemoTask struct {
+	models.BaseModel
+	Title  string     `gorm:"size:200;not null" json:"title"`
+	Status TaskStatus `gorm:"size:20;not null;default:'todo'" json:"status"`
+}
+
+func (DemoTask) TableName() string {
+	return "demo_tasks"
+}

package/template/apps/server/internal/modules/demo/domain/service/errors.go

@@ -0,0 +1,9 @@
+package service
+
+import "errors"
+
+var (
+	ErrTaskNotFound  = errors.New("task not found")
+	ErrTitleRequired = errors.New("title is required")
+	ErrStatusInvalid = errors.New("status is invalid")
+)

package/template/apps/server/internal/modules/demo/domain/service/task_service.go

@@ -0,0 +1,95 @@
+package service
+
+import (
+	"context"
+	"strings"
+
+	"__APP_NAME__/apps/server/internal/modules/demo/domain/models"
+)
+
+type TaskRepository interface {
+	List(ctx context.Context, tenantID uint) ([]models.DemoTask, error)
+	FindByID(tenantID, id uint) (*models.DemoTask, error)
+	Create(ctx context.Context, task *models.DemoTask) error
+	Update(ctx context.Context, task *models.DemoTask) error
+	Delete(ctx context.Context, task *models.DemoTask) error
+}
+
+type TaskService struct {
+	tasks TaskRepository
+}
+
+type TaskInput struct {
+	Title  string
+	Status models.TaskStatus
+}
+
+type TaskUpdateInput struct {
+	Title  string
+	Status models.TaskStatus
+}
+
+func NewTaskService(tasks TaskRepository) *TaskService {
+	return &TaskService{tasks: tasks}
+}
+
+func (s *TaskService) List(ctx context.Context, tenantID uint) ([]models.DemoTask, error) {
+	return s.tasks.List(ctx, tenantID)
+}
+
+func (s *TaskService) Create(ctx context.Context, tenantID uint, input TaskInput) (*models.DemoTask, error) {
+	title := strings.TrimSpace(input.Title)
+	if title == "" {
+		return nil, ErrTitleRequired
+	}
+
+	status := input.Status
+	if status == "" {
+		status = models.StatusTodo
+	}
+	if !status.IsValid() {
+		return nil, ErrStatusInvalid
+	}
+
+	task := &models.DemoTask{
+		Title:  title,
+		Status: status,
+	}
+	task.TenantID = tenantID
+
+	if err := s.tasks.Create(ctx, task); err != nil {
+		return nil, err
+	}
+	return task, nil
+}
+
+func (s *TaskService) Update(ctx context.Context, tenantID, id uint, input TaskUpdateInput) (*models.DemoTask, error) {
+	task, err := s.tasks.FindByID(tenantID, id)
+	if err != nil {
+		return nil, err
+	}
+
+	if title := strings.TrimSpace(input.Title); title != "" {
+		task.Title = title
+	}
+
+	if input.Status != "" {
+		if !input.Status.IsValid() {
+			return nil, ErrStatusInvalid
+		}
+		task.Status = input.Status
+	}
+
+	if err := s.tasks.Update(ctx, task); err != nil {
+		return nil, err
+	}
+	return task, nil
+}
+
+func (s *TaskService) Delete(ctx context.Context, tenantID, id uint) error {
+	task, err := s.tasks.FindByID(tenantID, id)
+	if err != nil {
+		return err
+	}
+	return s.tasks.Delete(ctx, task)
+}

package/template/apps/server/internal/modules/demo/infra/repository/task_repository.go

@@ -0,0 +1,49 @@
+package repository
+
+import (
+	"context"
+	"errors"
+
+	"gorm.io/gorm"
+
+	"__APP_NAME__/apps/server/internal/modules/demo/domain/models"
+	"__APP_NAME__/apps/server/internal/modules/demo/domain/service"
+)
+
+type TaskRepository struct {
+	db *gorm.DB
+}
+
+func NewTaskRepository(db *gorm.DB) *TaskRepository {
+	return &TaskRepository{db: db}
+}
+
+func (r *TaskRepository) List(ctx context.Context, tenantID uint) ([]models.DemoTask, error) {
+	var tasks []models.DemoTask
+	err := r.db.WithContext(ctx).
+		Where("tenant_id = ?", tenantID).
+		Order("created_at desc").
+		Find(&tasks).Error
+	return tasks, err
+}
+
+func (r *TaskRepository) FindByID(tenantID, id uint) (*models.DemoTask, error) {
+	var task models.DemoTask
+	err := r.db.Where("tenant_id = ? AND id = ?", tenantID, id).First(&task).Error
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return nil, service.ErrTaskNotFound
+	}
+	return &task, err
+}
+
+func (r *TaskRepository) Create(ctx context.Context, task *models.DemoTask) error {
+	return r.db.WithContext(ctx).Create(task).Error
+}
+
+func (r *TaskRepository) Update(ctx context.Context, task *models.DemoTask) error {
+	return r.db.WithContext(ctx).Save(task).Error
+}
+
+func (r *TaskRepository) Delete(ctx context.Context, task *models.DemoTask) error {
+	return r.db.WithContext(ctx).Delete(task).Error
+}

package/template/apps/server/internal/modules/demo/module.go

@@ -6,27 +6,47 @@ import (
 
 	"github.com/robsuncn/keystone/domain/permissions"
 	"github.com/robsuncn/keystone/infra/jobs"
+
+	demohandler "__APP_NAME__/apps/server/internal/modules/demo/api/handler"
+	demomigrations "__APP_NAME__/apps/server/internal/modules/demo/bootstrap/migrations"
+	demoseeds "__APP_NAME__/apps/server/internal/modules/demo/bootstrap/seeds"
+	demomodels "__APP_NAME__/apps/server/internal/modules/demo/domain/models"
+	demoservice "__APP_NAME__/apps/server/internal/modules/demo/domain/service"
+	demorepository "__APP_NAME__/apps/server/internal/modules/demo/infra/repository"
 )
 
-type Module struct{}
+type Module struct {
+	tasks *demoservice.TaskService
+}
 
-func NewModule() Module {
-	return Module{}
+func NewModule() *Module {
+	return &Module{}
 }
 
-func (Module) Name() string {
+func (m *Module) Name() string {
 	return "demo"
 }
 
-func (Module) RegisterRoutes(rg *gin.RouterGroup) {
-	registerRoutes(rg)
+func (m *Module) RegisterRoutes(rg *gin.RouterGroup) {
+	if rg == nil || m == nil {
+		return
+	}
+	handler := demohandler.NewTaskHandler(m.tasks)
+	if handler == nil {
+		return
+	}
+	group := rg.Group("/demo")
+	group.GET("/tasks", handler.List)
+	group.POST("/tasks", handler.Create)
+	group.PATCH("/tasks/:id", handler.Update)
+	group.DELETE("/tasks/:id", handler.Delete)
 }
 
-func (Module) RegisterModels() []interface{} {
-	return nil
+func (m *Module) RegisterModels() []interface{} {
+	return []interface{}{&demomodels.DemoTask{}}
 }
 
-func (Module) RegisterPermissions(reg *permissions.Registry) error {
+func (m *Module) RegisterPermissions(reg *permissions.Registry) error {
 	if reg == nil {
 		return nil
 	}
@@ -42,14 +62,30 @@ func (Module) RegisterPermissions(reg *permissions.Registry) error {
 	return nil
 }
 
-func (Module) RegisterJobs(_ *jobs.Registry) error {
+func (m *Module) RegisterJobs(_ *jobs.Registry) error {
 	return nil
 }
 
-func (Module) Migrate(_ *gorm.DB) error {
-	return nil
+func (m *Module) Migrate(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+	m.ensureServices(db)
+	return demomigrations.Migrate(db)
 }
 
-func (Module) Seed(_ *gorm.DB) error {
-	return nil
+func (m *Module) Seed(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+	m.ensureServices(db)
+	return demoseeds.Seed(db)
+}
+
+func (m *Module) ensureServices(db *gorm.DB) {
+	if m == nil || db == nil || m.tasks != nil {
+		return
+	}
+	repo := demorepository.NewTaskRepository(db)
+	m.tasks = demoservice.NewTaskService(repo)
 }

package/template/apps/server/internal/modules/example/handlers.go

@@ -0,0 +1,19 @@
+package example
+
+import (
+	"github.com/gin-gonic/gin"
+
+	"github.com/robsuncn/keystone/api/response"
+)
+
+type HelloResponse struct {
+	Message string `json:"message"`
+	Module  string `json:"module"`
+}
+
+func handleHello(c *gin.Context) {
+	response.Success(c, HelloResponse{
+		Message: "Hello from Example module!",
+		Module:  "example",
+	})
+}

package/template/apps/server/internal/modules/example/module.go

@@ -0,0 +1,53 @@
+package example
+
+import (
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	"github.com/robsuncn/keystone/domain/permissions"
+	"github.com/robsuncn/keystone/infra/jobs"
+)
+
+type Module struct{}
+
+func NewModule() Module {
+	return Module{}
+}
+
+func (Module) Name() string {
+	return "example"
+}
+
+func (Module) RegisterRoutes(rg *gin.RouterGroup) {
+	if rg == nil {
+		return
+	}
+	group := rg.Group("/example")
+	group.GET("/hello", handleHello)
+}
+
+func (Module) RegisterModels() []interface{} {
+	return nil
+}
+
+func (Module) RegisterPermissions(reg *permissions.Registry) error {
+	if reg == nil {
+		return nil
+	}
+	if err := reg.CreateMenu("example:main", "Example", "example", 100); err != nil {
+		return err
+	}
+	return reg.CreateAction("example:view", "View Example", "example", "example:main")
+}
+
+func (Module) RegisterJobs(_ *jobs.Registry) error {
+	return nil
+}
+
+func (Module) Migrate(_ *gorm.DB) error {
+	return nil
+}
+
+func (Module) Seed(_ *gorm.DB) error {
+	return nil
+}

package/template/apps/server/internal/modules/manifest.go

@@ -1,11 +1,13 @@
 package modules
 
 import (
-	demo "__APP_NAME__/apps/server/internal/modules/demo"
+demo "__APP_NAME__/apps/server/internal/modules/demo"
+example "__APP_NAME__/apps/server/internal/modules/example"
 )
 
 // RegisterAll wires the module registry for this app.
 func RegisterAll() {
 	Clear()
+	Register(example.NewModule())
 	Register(demo.NewModule())
 }

package/template/apps/web/node_modules/.bin/acorn

@@ -0,0 +1,17 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*) basedir=`cygpath -w "$basedir"`;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/mnt/c/Rob/source/projects/keystone/packages/create-keystone-app/template/node_modules/.pnpm/acorn@8.15.0/node_modules/acorn/bin/node_modules:/mnt/c/Rob/source/projects/keystone/packages/create-keystone-app/template/node_modules/.pnpm/acorn@8.15.0/node_modules/acorn/node_modules:/mnt/c/Rob/source/projects/keystone/packages/create-keystone-app/template/node_modules/.pnpm/acorn@8.15.0/node_modules:/mnt/c/Rob/source/projects/keystone/packages/create-keystone-app/template/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/mnt/c/Rob/source/projects/keystone/packages/create-keystone-app/template/node_modules/.pnpm/acorn@8.15.0/node_modules/acorn/bin/node_modules:/mnt/c/Rob/source/projects/keystone/packages/create-keystone-app/template/node_modules/.pnpm/acorn@8.15.0/node_modules/acorn/node_modules:/mnt/c/Rob/source/projects/keystone/packages/create-keystone-app/template/node_modules/.pnpm/acorn@8.15.0/node_modules:/mnt/c/Rob/source/projects/keystone/packages/create-keystone-app/template/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../../../../node_modules/.pnpm/acorn@8.15.0/node_modules/acorn/bin/acorn" "$@"
+else
+  exec node  "$basedir/../../../../node_modules/.pnpm/acorn@8.15.0/node_modules/acorn/bin/acorn" "$@"
+fi