@robsun/create-keystone-app 0.1.18 → 0.2.1

package/template/apps/web/src/modules/example/help/overview.md

@@ -1,11 +1,25 @@
 ---
 helpKey: "example/overview"
-title: "Example Module"
-description: "Quick tour of the example module."
+title: "Example Module Overview"
+description: "Overview of the Example module and its full CRUD flow."
 category: "example"
-tags: ["example", "starter"]
+tags: ["example", "items", "crud"]
 ---
 
 # Example Module
 
-Use this page to see how routes, permissions, and API calls connect together.
+Example 模块演示完整的 CRUD、权限命名与前后端分层结构，适合作为新模块开发参考。
+
+## 你能看到什么
+- 前端模块注册（`index.ts`）与路由配置（`routes.tsx`）
+- CRUD 页面与 API 调用（`pages/` + `services/`）
+- 后端 DDD 分层（`domain/` + `infra/` + `bootstrap/`）
+- 权限注册与菜单同步（`RegisterPermissions`）
+
+## 关键文件
+- 前端：`apps/web/src/modules/example/`
+- 后端：`apps/server/internal/modules/example/`
+
+## API 与权限
+- API：`/api/v1/example/items`
+- 权限：`example:item:view`、`example:item:manage`

package/template/apps/web/src/modules/example/pages/ExampleItemsPage.tsx

@@ -0,0 +1,227 @@
+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 dayjs from 'dayjs'
+import {
+  createExampleItem,
+  deleteExampleItem,
+  listExampleItems,
+  updateExampleItem,
+} from '../services/exampleItems'
+import type { ExampleItem, ExampleItemStatus } from '../types'
+
+type ExampleItemFormValues = {
+  title: string
+  description?: string
+  status: ExampleItemStatus
+}
+
+const statusMeta: Record<ExampleItemStatus, { label: string; color: string }> = {
+  active: { label: 'Active', color: 'success' },
+  inactive: { label: 'Inactive', color: 'default' },
+}
+
+const statusOptions = [
+  { value: 'active', label: 'Active' },
+  { value: 'inactive', label: 'Inactive' },
+]
+
+export function ExampleItemsPage() {
+  const { message } = App.useApp()
+  const [items, setItems] = useState<ExampleItem[]>([])
+  const [loading, setLoading] = useState(false)
+  const [modalOpen, setModalOpen] = useState(false)
+  const [saving, setSaving] = useState(false)
+  const [editingItem, setEditingItem] = useState<ExampleItem | null>(null)
+  const [form] = Form.useForm<ExampleItemFormValues>()
+
+  const fetchItems = useCallback(async () => {
+    setLoading(true)
+    try {
+      const data = await listExampleItems()
+      setItems(data)
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : 'Failed to load items'
+      message.error(detail)
+    } finally {
+      setLoading(false)
+    }
+  }, [message])
+
+  useEffect(() => {
+    void fetchItems()
+  }, [fetchItems])
+
+  const openCreate = useCallback(() => {
+    setEditingItem(null)
+    form.resetFields()
+    form.setFieldsValue({ status: 'active' })
+    setModalOpen(true)
+  }, [form])
+
+  const openEdit = useCallback(
+    (item: ExampleItem) => {
+      setEditingItem(item)
+      form.setFieldsValue({
+        title: item.title,
+        description: item.description,
+        status: item.status,
+      })
+      setModalOpen(true)
+    },
+    [form]
+  )
+
+  const closeModal = useCallback(() => {
+    setModalOpen(false)
+    setEditingItem(null)
+    form.resetFields()
+  }, [form])
+
+  const handleSubmit = useCallback(async () => {
+    let values: ExampleItemFormValues
+    try {
+      values = await form.validateFields()
+    } catch {
+      return
+    }
+
+    const payload = {
+      title: values.title.trim(),
+      description: values.description?.trim() ?? '',
+      status: values.status,
+    }
+
+    setSaving(true)
+    try {
+      if (editingItem) {
+        await updateExampleItem(editingItem.id, payload)
+        message.success('Item updated')
+      } else {
+        await createExampleItem(payload)
+        message.success('Item created')
+      }
+      closeModal()
+      await fetchItems()
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : 'Failed to save item'
+      message.error(detail)
+    } finally {
+      setSaving(false)
+    }
+  }, [closeModal, editingItem, fetchItems, form, message])
+
+  const handleDelete = useCallback(
+    async (id: number) => {
+      try {
+        await deleteExampleItem(id)
+        await fetchItems()
+        message.success('Item deleted')
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : 'Failed to delete item'
+        message.error(detail)
+      }
+    },
+    [fetchItems, message]
+  )
+
+  const columns: ColumnsType<ExampleItem> = useMemo(
+    () => [
+      { title: 'Title', dataIndex: 'title', key: 'title' },
+      {
+        title: 'Description',
+        dataIndex: 'description',
+        key: 'description',
+        render: (value: string) =>
+          value ? <Typography.Text type="secondary">{value}</Typography.Text> : '-',
+      },
+      {
+        title: 'Status',
+        dataIndex: 'status',
+        key: 'status',
+        render: (value: ExampleItemStatus) => {
+          const meta = statusMeta[value]
+          return <Tag color={meta.color}>{meta.label}</Tag>
+        },
+      },
+      {
+        title: 'Updated',
+        dataIndex: 'updated_at',
+        key: 'updated_at',
+        render: (value: string) => (value ? dayjs(value).format('YYYY-MM-DD HH:mm') : '-'),
+      },
+      {
+        title: 'Actions',
+        key: 'actions',
+        render: (_, record) => (
+          <Space>
+            <Button type="link" onClick={() => openEdit(record)}>
+              Edit
+            </Button>
+            <Popconfirm title="Delete this item?" onConfirm={() => handleDelete(record.id)}>
+              <Button type="link" danger>
+                Delete
+              </Button>
+            </Popconfirm>
+          </Space>
+        ),
+      },
+    ],
+    [handleDelete, openEdit]
+  )
+
+  return (
+    <Card
+      title="Example Items"
+      extra={
+        <Space>
+          <Button onClick={fetchItems} loading={loading}>
+            Refresh
+          </Button>
+          <Button type="primary" onClick={openCreate}>
+            New Item
+          </Button>
+        </Space>
+      }
+    >
+      <Space direction="vertical" size="middle" style={{ width: '100%' }}>
+        <Typography.Text type="secondary">
+          This page demonstrates a full CRUD workflow wired to the Example module API.
+        </Typography.Text>
+        <Table<ExampleItem>
+          rowKey="id"
+          loading={loading}
+          columns={columns}
+          dataSource={items}
+          pagination={false}
+        />
+      </Space>
+
+      <Modal
+        title={editingItem ? 'Edit Item' : 'New Item'}
+        open={modalOpen}
+        onCancel={closeModal}
+        onOk={handleSubmit}
+        confirmLoading={saving}
+        okText={editingItem ? 'Save' : 'Create'}
+        destroyOnClose
+      >
+        <Form form={form} layout="vertical" initialValues={{ status: 'active' }}>
+          <Form.Item
+            label="Title"
+            name="title"
+            rules={[{ required: true, whitespace: true, message: 'Title is required' }]}
+          >
+            <Input placeholder="Item title" allowClear />
+          </Form.Item>
+          <Form.Item label="Description" name="description">
+            <Input.TextArea rows={3} placeholder="Short description" />
+          </Form.Item>
+          <Form.Item label="Status" name="status" rules={[{ required: true, message: 'Select status' }]}>
+            <Select options={statusOptions} />
+          </Form.Item>
+        </Form>
+      </Modal>
+    </Card>
+  )
+}

package/template/apps/web/src/modules/example/routes.tsx

@@ -1,20 +1,43 @@
-import { lazy } from 'react'
+import { lazy, Suspense, type ComponentType, type ReactElement } from 'react'
 import type { RouteObject } from 'react-router-dom'
-import { QuestionCircleOutlined } from '@ant-design/icons'
+import { AppstoreOutlined } from '@ant-design/icons'
+import { Spin } from 'antd'
 
-const ExamplePage = lazy(() =>
-  import('./pages/ExamplePage').then((m) => ({ default: m.ExamplePage }))
+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 ExampleItemsPage = lazyNamed(() => import('./pages/ExampleItemsPage'), 'ExampleItemsPage')
+
 export const exampleRoutes: RouteObject[] = [
   {
     path: 'example',
-    element: <ExamplePage />,
+    element: <ExampleItemsPage />,
     handle: {
-      menu: { label: 'Example', icon: <QuestionCircleOutlined /> },
-      breadcrumb: 'Example',
-      permission: 'example:view',
-      helpKey: 'example/overview',
+      menu: { label: 'Example Items', icon: <AppstoreOutlined />, permission: 'example:item:view' },
+      breadcrumb: 'Example Items',
+      permission: 'example:item:view',
+      helpKey: 'example/items',
     },
   },
-]
+].map((route) => ({
+  ...route,
+  element: route.element ? withSuspense(route.element) : route.element,
+}))

package/template/apps/web/src/modules/example/services/exampleItems.ts

@@ -0,0 +1,32 @@
+import { api, type ApiResponse } from '@robsun/keystone-web-core'
+import type { ExampleItem, ExampleItemStatus } from '../types'
+
+type ItemListResponse = {
+  items: ExampleItem[]
+}
+
+export const listExampleItems = async () => {
+  const { data } = await api.get<ApiResponse<ItemListResponse>>('/example/items')
+  return data.data.items
+}
+
+export const createExampleItem = async (payload: {
+  title: string
+  description?: string
+  status?: ExampleItemStatus
+}) => {
+  const { data } = await api.post<ApiResponse<ExampleItem>>('/example/items', payload)
+  return data.data
+}
+
+export const updateExampleItem = async (
+  id: number,
+  payload: { title?: string; description?: string; status?: ExampleItemStatus }
+) => {
+  const { data } = await api.patch<ApiResponse<ExampleItem>>(`/example/items/${id}`, payload)
+  return data.data
+}
+
+export const deleteExampleItem = async (id: number) => {
+  await api.delete<ApiResponse<{ id: number }>>(`/example/items/${id}`)
+}

package/template/apps/web/src/modules/example/types.ts

@@ -0,0 +1,10 @@
+export type ExampleItemStatus = 'active' | 'inactive'
+
+export interface ExampleItem {
+  id: number
+  title: string
+  description: string
+  status: ExampleItemStatus
+  created_at: string
+  updated_at: string
+}

package/template/docs/CONVENTIONS.md

@@ -88,6 +88,50 @@ type Module interface {
 - 在 `apps/server/config.yaml` 的 `modules.enabled` 启用模块。
 - Web 端 `app.config.ts` 保持同名启用列表。
 
+## 权限命名与同步
+- 命名规范：`{module}:{resource}:{action}`，例如：`example:item:view`。
+- 菜单权限通常使用 `{module}:{resource}`，用于菜单与分组，例如：`example:item`。
+- 前端使用 `routes.tsx` 的 `handle.permission` 与 `handle.menu.permission` 控制路由/菜单访问。
+- 后端使用 `RegisterPermissions` 注册同名权限，确保权限种子与管理后台一致。
+
+示例（后端注册）：
+```go
+if err := reg.CreateMenu("example:item", "Example Items", "example", 10); err != nil {
+    return err
+}
+if err := reg.CreateAction("example:item:view", "View Items", "example", "example:item"); err != nil {
+    return err
+}
+if err := reg.CreateAction("example:item:manage", "Manage Items", "example", "example:item"); err != nil {
+    return err
+}
+```
+
+示例（前端路由）：
+```tsx
+{
+  path: 'example',
+  element: <ExampleItemsPage />,
+  handle: {
+    menu: { label: 'Example Items', icon: <AppstoreOutlined />, permission: 'example:item:view' },
+    breadcrumb: 'Example Items',
+    permission: 'example:item:view',
+    helpKey: 'example/items',
+  },
+}
+```
+
+权限同步流程（简化）：
+```
+routes.tsx handle.permission
+        ↓
+登录接口返回权限列表（permissions）
+        ↓
+前端菜单/路由/按钮显示与否
+        ↓
+RegisterPermissions 负责定义权限种子与后台管理项
+```
+
 ## 迁移 / 种子 / 权限
 - `startup.InitializeDatabase` 统一执行：核心迁移 + 模块迁移 + 种子 + 权限注册。
 - 模块权限通过 `RegisterPermissions` 注入。

package/template/docs/GETTING_STARTED.md

@@ -0,0 +1,54 @@
+# 10 分钟上手 Keystone
+
+## 1) 快速启动（约 2 分钟）
+```bash
+pnpm install
+pnpm dev
+```
+- Web 端口：`http://localhost:3000`
+- Server 端口：`http://localhost:8080`
+- 默认账号：`admin` / `Admin123!`（Tenant: `default`）
+
+## 2) 认识项目结构
+- `apps/web/`：React + Vite 壳与业务模块（`src/modules/*`）。
+- `apps/server/`：Go 服务端与模块注册（`internal/modules/*`）。
+- `docs/`：开发规范与约定。
+- `scripts/`：跨平台 dev/build/test/clean。
+
+## 3) 理解 Example 模块（前后端对照）
+- 前端模块：
+  - `apps/web/src/modules/example/`
+  - 入口：`index.ts`（模块注册）
+  - 路由与权限：`routes.tsx`
+  - 页面与 API：`pages/` + `services/`
+- 后端模块：
+  - `apps/server/internal/modules/example/`
+  - 入口：`module.go`
+  - API：`api/handler/`
+  - 领域：`domain/` + `infra/` + `bootstrap/`
+
+## 4) 创建你的第一个模块（复制 Example）
+1. 复制前端模块：
+   - `apps/web/src/modules/example` → `apps/web/src/modules/orders`
+2. 修改模块名称与权限：
+   - 更新 `routes.tsx`、`help/*.md`、`services/*` 中的路径与权限前缀。
+3. 注册前端模块：
+   - 在 `apps/web/src/main.tsx` 添加 `import './modules/orders'`
+   - 在 `apps/web/src/app.config.ts` 的 `modules.enabled` 加入 `orders`
+4. 复制后端模块：
+   - `apps/server/internal/modules/example` → `apps/server/internal/modules/orders`
+5. 修改后端模块名称：
+   - 更新 `module.go` 中的 `Name()` 与权限注册
+6. 注册后端模块：
+   - 在 `apps/server/internal/modules/manifest.go` 注册新模块
+   - 在 `apps/server/config.yaml` 的 `modules.enabled` 加入 `orders`
+
+## 5) 常见问题（FAQ）
+**Q: 页面空白或 404？**  
+A: 确认 `pnpm dev` 正常启动，`modules.enabled` 前后端一致，且前端已在 `main.tsx` 导入模块。
+
+**Q: 权限不足导致按钮不可用？**  
+A: 检查后端 `RegisterPermissions` 是否注册对应权限，并确认当前用户拥有权限。
+
+**Q: API 报错或返回空列表？**  
+A: 检查服务端日志、数据库连接、`apps/server/config.yaml` 是否正确。

package/template/package.json

@@ -7,7 +7,8 @@
     "build": "node scripts/build.js",
     "build:web": "pnpm --filter web build",
     "check-modules": "node scripts/check-modules.js",
-    "test": "node scripts/test.js",
+    "create:module": "pnpm dlx --package @robsun/create-keystone-app create-keystone-module",
+    "test": "pnpm check-modules && node scripts/test.js",
     "lint": "pnpm --filter web lint",
     "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md,yml,yaml}\"",
     "clean": "node scripts/clean.js",

package/template/scripts/check-modules.js

@@ -41,7 +41,7 @@ function parseServerModules(content) {
 }
 
 function formatList(items) {
-  return items.map((item) => `- ${item}`).join('\n')
+  return items.map((item) => `  - ${item}`).join('\n')
 }
 
 try {
@@ -60,6 +60,10 @@ try {
   }
 
   console.error('Module configuration mismatch:')
+  console.error('\napps/web/src/app.config.ts modules.enabled:')
+  console.error(formatList(webModules))
+  console.error('\napps/server/config.yaml modules.enabled:')
+  console.error(formatList(serverModules))
   if (missingInServer.length > 0) {
     console.error('\nMissing in apps/server/config.yaml:')
     console.error(formatList(missingInServer))
@@ -68,9 +72,11 @@ try {
     console.error('\nMissing in apps/web/src/app.config.ts:')
     console.error(formatList(missingInWeb))
   }
+  console.error('\nFix: keep module names identical in both files and register modules in main.tsx/manifest.go.')
   process.exit(1)
 } catch (err) {
   console.error('Failed to check modules:')
   console.error(err instanceof Error ? err.message : String(err))
+  console.error('Hint: verify apps/web/src/app.config.ts and apps/server/config.yaml exist and are valid.')
   process.exit(2)
 }

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

@@ -1,152 +0,0 @@
-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

@@ -1,21 +0,0 @@
-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
-}