@robsun/create-keystone-app 0.1.18 → 0.2.0

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

@@ -6,48 +6,86 @@ import (
 
 	"github.com/robsuncn/keystone/domain/permissions"
 	"github.com/robsuncn/keystone/infra/jobs"
+
+	examplehandler "__APP_NAME__/apps/server/internal/modules/example/api/handler"
+	examplemigrations "__APP_NAME__/apps/server/internal/modules/example/bootstrap/migrations"
+	exampleseeds "__APP_NAME__/apps/server/internal/modules/example/bootstrap/seeds"
+	examplemodels "__APP_NAME__/apps/server/internal/modules/example/domain/models"
+	exampleservice "__APP_NAME__/apps/server/internal/modules/example/domain/service"
+	examplerepository "__APP_NAME__/apps/server/internal/modules/example/infra/repository"
 )
 
-type Module struct{}
+type Module struct {
+	items *exampleservice.ItemService
+}
 
-func NewModule() Module {
-	return Module{}
+func NewModule() *Module {
+	return &Module{}
 }
 
-func (Module) Name() string {
+func (m *Module) Name() string {
 	return "example"
 }
 
-func (Module) RegisterRoutes(rg *gin.RouterGroup) {
-	if rg == nil {
+func (m *Module) RegisterRoutes(rg *gin.RouterGroup) {
+	if rg == nil || m == nil {
+		return
+	}
+	handler := examplehandler.NewItemHandler(m.items)
+	if handler == nil {
 		return
 	}
 	group := rg.Group("/example")
-	group.GET("/hello", handleHello)
+	group.GET("/items", handler.List)
+	group.POST("/items", handler.Create)
+	group.PATCH("/items/:id", handler.Update)
+	group.DELETE("/items/:id", handler.Delete)
 }
 
-func (Module) RegisterModels() []interface{} {
-	return nil
+func (m *Module) RegisterModels() []interface{} {
+	return []interface{}{&examplemodels.ExampleItem{}}
 }
 
-func (Module) RegisterPermissions(reg *permissions.Registry) error {
+func (m *Module) RegisterPermissions(reg *permissions.Registry) error {
 	if reg == nil {
 		return nil
 	}
-	if err := reg.CreateMenu("example:main", "Example", "example", 100); err != nil {
+	if err := reg.CreateMenu("example:item", "Example Items", "example", 10); err != nil {
 		return err
 	}
-	return reg.CreateAction("example:view", "View Example", "example", "example:main")
+	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
+	}
+	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 examplemigrations.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 exampleseeds.Seed(db)
+}
+
+func (m *Module) ensureServices(db *gorm.DB) {
+	if m == nil || db == nil || m.items != nil {
+		return
+	}
+	repo := examplerepository.NewItemRepository(db)
+	m.items = exampleservice.NewItemService(repo)
 }

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

@@ -1,13 +1,11 @@
 package modules
 
 import (
-demo "__APP_NAME__/apps/server/internal/modules/demo"
-example "__APP_NAME__/apps/server/internal/modules/example"
+	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/src/app.config.ts

@@ -8,7 +8,7 @@ export const appConfig: Partial<KeystoneWebConfig> = {
     platformName: 'Keystone Platform',
   },
   modules: {
-    enabled: ['keystone', 'example', 'demo'],
+    enabled: ['keystone', 'example'],
   },
   approval: {
     businessTypes: [{ value: 'general', label: 'General Flow' }],

package/template/apps/web/src/main.tsx

@@ -6,7 +6,6 @@ import { appConfig } from './app.config'
 import '@robsun/keystone-web-core/styles/keystone.css'
 import './index.css'
 import './modules/example'
-import './modules/demo'
 
 setKeystoneConfig(appConfig)
 const dayjsLocale = getKeystoneConfig().ui?.locale?.dayjs ?? 'en'

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

@@ -0,0 +1,23 @@
+---
+helpKey: "example/faq"
+title: "Example Module FAQ"
+description: "Common questions for the Example module."
+category: "example"
+tags: ["example", "faq"]
+---
+
+# FAQ
+
+## 为什么列表为空？
+- 确认已运行迁移与种子（首次启动会自动执行）。
+- 检查当前用户是否有 `example:item:view` 权限。
+- 确认 `modules.enabled` 中已启用 `example`。
+
+## 为什么保存失败？
+- Title 必填，且不能为空字符串。
+- 状态仅支持 `active` / `inactive`。
+- 查看后端日志获取更详细错误信息。
+
+## 为什么前后端权限不一致？
+- 检查 `routes.tsx` 中的 `handle.permission`。
+- 检查 `RegisterPermissions` 中的权限注册是否一致。

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

@@ -0,0 +1,26 @@
+---
+helpKey: "example/items"
+title: "Example Items"
+description: "Manage example items with full CRUD operations."
+category: "example"
+tags: ["example", "items", "crud"]
+---
+
+# Example Items
+
+该页面展示 Example 模块的完整 CRUD 流程，适合用来对照学习：
+
+## 字段说明
+- **Title**：必填，标题信息。
+- **Description**：可选，简短描述。
+- **Status**：`active` / `inactive`。
+
+## 权限建议
+- `example:item:view`：访问列表与详情。
+- `example:item:manage`：创建、编辑、删除。
+
+## API 端点
+- `GET /api/v1/example/items`
+- `POST /api/v1/example/items`
+- `PATCH /api/v1/example/items/:id`
+- `DELETE /api/v1/example/items/:id`

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,7 @@
     "build": "node scripts/build.js",
     "build:web": "pnpm --filter web build",
     "check-modules": "node scripts/check-modules.js",
-    "test": "node scripts/test.js",
+    "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",