@robsun/create-keystone-app 0.2.15 → 0.4.1

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

@@ -1,97 +1,171 @@
-package example
-
-import (
-	"github.com/gin-gonic/gin"
-	"gorm.io/gorm"
-
-	"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"
-	examplei18n "__APP_NAME__/apps/server/internal/modules/example/i18n"
-	examplerepository "__APP_NAME__/apps/server/internal/modules/example/infra/repository"
-)
-
-type Module struct {
-	items *exampleservice.ItemService
-}
-
-func NewModule() *Module {
-	return &Module{}
-}
-
-func (m *Module) Name() string {
-	return "example"
-}
-
-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("/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{}{&examplemodels.ExampleItem{}}
-}
-
-func (m *Module) RegisterPermissions(reg *permissions.Registry) error {
-	if reg == nil {
-		return nil
-	}
-	// Use NameKey for i18n support
-	if err := reg.CreateMenuI18n("example:item", "Example Items", "permission.example.item", "example", 10); err != nil {
-		return err
-	}
-	if err := reg.CreateActionI18n("example:item:view", "View Items", "permission.example.item.view", "example", "example:item"); err != nil {
-		return err
-	}
-	if err := reg.CreateActionI18n("example:item:manage", "Manage Items", "permission.example.item.manage", "example", "example:item"); err != nil {
-		return err
-	}
-	return nil
-}
-
-func (m *Module) RegisterI18n() error {
-	return examplei18n.RegisterLocales()
-}
-
-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 examplemigrations.Migrate(db)
-}
-
-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 example
+
+import (
+	"github.com/gin-gonic/gin"
+	"gorm.io/gorm"
+
+	approvalRepo "github.com/robsuncn/keystone/domain/approval/repository"
+	approvalSvc "github.com/robsuncn/keystone/domain/approval/service"
+	"github.com/robsuncn/keystone/domain/permissions"
+	"github.com/robsuncn/keystone/domain/service"
+	"github.com/robsuncn/keystone/infra/exporter"
+	"github.com/robsuncn/keystone/infra/importer"
+	"github.com/robsuncn/keystone/infra/repository"
+	"github.com/robsuncn/keystone/infra/scheduler"
+
+	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"
+	examplei18n "__APP_NAME__/apps/server/internal/modules/example/i18n"
+	exampleexporter "__APP_NAME__/apps/server/internal/modules/example/infra/exporter"
+	exampleimporter "__APP_NAME__/apps/server/internal/modules/example/infra/importer"
+	examplerepository "__APP_NAME__/apps/server/internal/modules/example/infra/repository"
+	servermodules "github.com/robsuncn/keystone/server/modules"
+)
+
+type Module struct {
+	db    *gorm.DB
+	items *exampleservice.ItemService
+}
+
+func NewModule() *Module {
+	return &Module{}
+}
+
+func (m *Module) Name() string {
+	return "example"
+}
+
+func (m *Module) RegisterRoutes(rg *gin.RouterGroup, deps servermodules.RouteDeps) {
+	if rg == nil || m == nil {
+		return
+	}
+	handler := examplehandler.NewItemHandler(m.items)
+	if handler == nil {
+		return
+	}
+	middlewares := make([]gin.HandlerFunc, 0, 1+len(deps.TenantGuards))
+	if deps.Auth != nil {
+		middlewares = append(middlewares, deps.Auth)
+	}
+	if len(deps.TenantGuards) > 0 {
+		middlewares = append(middlewares, deps.TenantGuards...)
+	}
+
+	group := rg.Group("/example", middlewares...)
+	viewGuard := permissionGuard(deps.RBAC, "example:item:view")
+	manageGuard := permissionGuard(deps.RBAC, "example:item:manage")
+
+	group.GET("/items", viewGuard, handler.List)
+	group.GET("/items/export/pdf", viewGuard, handler.ExportPDF)
+	group.GET("/items/import-template", manageGuard, handler.DownloadImportTemplate)
+	group.GET("/items/:id", viewGuard, handler.Get)
+	group.POST("/items", manageGuard, handler.Create)
+	group.PATCH("/items/:id", manageGuard, handler.Update)
+	group.DELETE("/items/:id", manageGuard, handler.Delete)
+	group.POST("/items/:id/submit", manageGuard, handler.Submit)
+	group.POST("/items/:id/cancel", manageGuard, handler.Cancel)
+}
+
+func (m *Module) RegisterModels() []interface{} {
+	return []interface{}{&examplemodels.ExampleItem{}}
+}
+
+func (m *Module) RegisterPermissions(reg *permissions.Registry) error {
+	if reg == nil {
+		return nil
+	}
+	// Use NameKey for i18n support
+	if err := reg.CreateMenuI18n("example:item", "Example Items", "permission.example.item", "example", 10); err != nil {
+		return err
+	}
+	if err := reg.CreateActionI18n("example:item:view", "View Items", "permission.example.item.view", "example", "example:item"); err != nil {
+		return err
+	}
+	if err := reg.CreateActionI18n("example:item:manage", "Manage Items", "permission.example.item.manage", "example", "example:item"); err != nil {
+		return err
+	}
+	return nil
+}
+
+func (m *Module) RegisterI18n() error {
+	return examplei18n.RegisterLocales()
+}
+
+func (m *Module) RegisterTasks(_ *scheduler.Registry) error {
+	return nil
+}
+
+func (m *Module) RegisterImporters(reg *importer.Service) error {
+	if reg == nil {
+		return nil
+	}
+	if m.items == nil && m.db != nil {
+		m.ensureServices(m.db)
+	}
+	return exampleimporter.RegisterItemImporter(reg, m.items)
+}
+
+func (m *Module) RegisterExporters(reg *exporter.Service) error {
+	if reg == nil {
+		return nil
+	}
+	if m.items == nil && m.db != nil {
+		m.ensureServices(m.db)
+	}
+	return exampleexporter.RegisterItemExporter(reg, m.items)
+}
+
+func (m *Module) Migrate(db *gorm.DB) error {
+	if db == nil {
+		return nil
+	}
+	m.ensureServices(db)
+	return examplemigrations.Migrate(db)
+}
+
+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
+	}
+	m.db = db
+	repo := examplerepository.NewItemRepository(db)
+
+	permRepo := repository.NewPermissionRepository(db)
+	userRepo := repository.NewUserRepository(db)
+	permSvc := service.NewPermissionService(permRepo, userRepo)
+
+	flowRepo := approvalRepo.NewFlowRepository(db)
+	nodeRepo := approvalRepo.NewNodeRepository(db)
+	instanceRepo := approvalRepo.NewInstanceRepository(db)
+	recordRepo := approvalRepo.NewRecordRepository(db)
+	approvalService := approvalSvc.NewService(db, instanceRepo, flowRepo, nodeRepo, recordRepo, userRepo, permSvc, approvalSvc.DefaultCallbackRegistry)
+	flowMatcher := approvalSvc.NewFlowMatcher(flowRepo)
+
+	notificationRepo := repository.NewNotificationRepository(db)
+	notificationSvc := service.NewNotificationService(db, notificationRepo)
+
+	callback := exampleservice.NewApprovalCallback(repo, notificationSvc)
+	approvalSvc.DefaultCallbackRegistry.Register(string(exampleservice.ApprovalBusinessType), callback)
+
+	m.items = exampleservice.NewItemService(repo, approvalService, flowMatcher, notificationSvc)
+}
+
+func permissionGuard(rbac servermodules.PermissionGuard, code string) gin.HandlerFunc {
+	if rbac == nil {
+		return func(c *gin.Context) {
+			c.Next()
+		}
+	}
+	return rbac.Require(code)
+}

package/template/apps/server/internal/modules/example/tests/integration_test.go

@@ -0,0 +1,7 @@
+package tests
+
+import "testing"
+
+func TestExampleIntegration(t *testing.T) {
+	t.Skip("integration test template")
+}

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

@@ -1,11 +1,11 @@
 package modules
 
-import (
-example "__APP_NAME__/apps/server/internal/modules/example"
-)
+import servermodules "github.com/robsuncn/keystone/server/modules"
 
-// RegisterAll wires the module registry for this app.
-func RegisterAll() {
-	Clear()
-	Register(example.NewModule())
+// Register wires application modules into the shared registry.
+func Register(registry *servermodules.Registry) {
+	if registry == nil {
+		return
+	}
+	registry.Register(servermodules.NewCoreModule())
 }

package/template/apps/web/README.md

@@ -8,20 +8,22 @@
 - `src/main.tsx`：应用入口。
 - `src/app.config.ts`：品牌与模块启用配置。
 - `src/modules/<module>/index.ts`：模块注册入口。
+- `src/modules/index.ts`：应用模块聚合入口。
 - `apps/web/.env.example`：前端环境变量模板（Vite 读取）。
 
 ## 新建模块
 1) 创建目录：`src/modules/<module>`。
 2) 在 `index.ts` 调用 `registerModule` 注册路由。
 3) 在 `routes.tsx` 配置菜单、权限、帮助文档。
-4) 在 `app.config.ts` 的 `modules.enabled` 启用模块。
+4) 在 `src/modules/index.ts` 引入模块。
+5) 在 `app.config.ts` 的 `modules.enabled` 启用模块。
 
 ## 帮助文档
 - 放在 `src/modules/<module>/help/**`。
 - `helpKey` 与路由 `handle.helpKey` 保持一致。
 
 ## 常用命令
-- 开发：`pnpm web:dev`
+- 开发：`pnpm dev`（前后端一起）/ `pnpm -C apps/web dev`（仅前端）
 - Lint：`pnpm -C apps/web lint`
 - 测试：`pnpm -C apps/web test`
 

package/template/apps/web/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@ant-design/icons": "^6.1.0",
-    "@robsun/keystone-web-core": "^0.3.0",
+    "@robsun/keystone-web-core": "^0.5.0",
     "antd": "^6.0.1",
     "dayjs": "^1.11.19",
     "i18next": "^24.2.3",

package/template/apps/web/src/app.config.ts

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

package/template/apps/web/src/index.css

@@ -1,3 +1,7 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+/*
+ * Tailwind 样式由 @robsun/keystone-web-core/styles/keystone.css 提供
+ * 如需添加自定义 Tailwind 工具类，使用 Tailwind v4 语法:
+ * @import 'tailwindcss/utilities';
+ */
+
+/* 应用级别的自定义样式可以放在这里 */

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

@@ -1,15 +1,12 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
-import dayjs from 'dayjs'
-import { KeystoneApp, getKeystoneConfig, setKeystoneConfig } from '@robsun/keystone-web-core'
+import { KeystoneApp, setKeystoneConfig } from '@robsun/keystone-web-core'
 import { appConfig } from './app.config'
 import '@robsun/keystone-web-core/styles/keystone.css'
 import './index.css'
-import './modules/example'
+import './modules'
 
 setKeystoneConfig(appConfig)
-const dayjsLocale = getKeystoneConfig().ui?.locale?.dayjs ?? 'en'
-dayjs.locale(dayjsLocale)
 
 createRoot(document.getElementById('root')!).render(
   <StrictMode>

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

@@ -0,0 +1,27 @@
+---
+helpKey: "example/faq"
+title: "Example Module FAQ"
+description: "Common questions for the Example module."
+category: "example"
+tags: ["example", "faq"]
+---
+
+# FAQ
+
+## Why is the list empty?
+- Confirm migrations and seed data have run (first launch runs them automatically).
+- Check the current user has the `example:item:view` permission.
+- Ensure `example` is enabled in `modules.enabled`.
+
+## Why does approval submission fail?
+- Confirm an approval flow exists and is enabled (a sample flow is created by default).
+- Check the current user is logged in and has submit permissions.
+- Status must be `draft` / `rejected` / `cancelled`.
+
+## Why can I not edit or delete?
+- `pending` status cannot be edited or deleted.
+- Approved records are read-only.
+
+## What if import fails?
+- Ensure import fields include `title`.
+- Category must be `general` / `operations` / `finance` / `growth`.

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

@@ -0,0 +1,30 @@
+---
+helpKey: "example/items"
+title: "Example Items"
+description: "Manage example items with CRUD, approval, import/export, and attachments."
+category: "example"
+tags: ["example", "items", "approval", "import", "export"]
+---
+
+# Example Items
+This page demonstrates the full lifecycle of example items, including creation, approval, import/export, and attachments.
+
+## Field reference
+- **Title**: required, item title.
+- **Description**: optional, item description.
+- **Category**: business category used for filters and approval conditions.
+- **Amount**: amount used for approval conditions and export.
+- **Status**: `draft` / `pending` / `approved` / `rejected` / `cancelled`.
+- **Attachment**: uploaded file stored in the file service.
+
+## Approval workflow
+- After submission, status becomes `pending` and is approved by the admin role.
+- Cancellation is supported; status becomes `cancelled` after cancel.
+
+## Import/Export
+- Import fields: `title`, `description`, `category`, `amount`, `status`.
+- Export includes ID, amount, approval status, and other fields.
+
+## Permissions
+- `example:item:view`: view list and details.
+- `example:item:manage`: create, edit, delete, submit/cancel approval.

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

@@ -0,0 +1,31 @@
+---
+helpKey: "example/overview"
+title: "Example Module Overview"
+description: "Overview of the Example module and the platform integrations it demonstrates."
+category: "example"
+tags: ["example", "items", "approval", "import", "export", "file"]
+---
+
+# Example Module
+The Example module demonstrates how a business module integrates platform capabilities and serves as a reference template for new module development.
+
+## Capabilities covered
+- CRUD with pagination and filters
+- RBAC permissions and menu registration
+- Approval workflow (submit, cancel, approval records)
+- Import/Export (Excel)
+- File upload and attachment storage
+- Notifications
+- i18n and Help docs
+
+## Key paths
+- Frontend: `apps/web/src/modules/example/`
+- Backend: `apps/server/internal/modules/example/`
+
+## Related APIs
+- `GET /api/v1/example/items`
+- `POST /api/v1/example/items`
+- `PATCH /api/v1/example/items/:id`
+- `DELETE /api/v1/example/items/:id`
+- `POST /api/v1/example/items/:id/submit`
+- `POST /api/v1/example/items/:id/cancel`

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

@@ -0,0 +1,27 @@
+---
+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`。
+
+## 为什么提交审批失败？
+- 确认审批流程已创建并启用（默认会创建示例流程）。
+- 检查当前用户是否已登录且具备提交权限。
+- 状态需为 `draft` / `rejected` / `cancelled`。
+
+## 为什么无法编辑或删除？
+- `pending` 状态下禁止编辑或删除。
+- 已审批通过的记录仅可查看。
+
+## 导入失败怎么办？
+- 检查导入字段是否包含 `title`。
+- 类别需为 `general` / `operations` / `finance` / `growth`。

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

@@ -0,0 +1,31 @@
+---
+helpKey: "example/items"
+title: "Example Items"
+description: "Manage example items with CRUD, approval, import/export, and attachments."
+category: "example"
+tags: ["example", "items", "approval", "import", "export"]
+---
+
+# Example Items
+
+本页展示示例事项的完整流程，覆盖创建、审批、导入/导出与附件。
+
+## 字段说明
+- **Title**：必填，事项标题。
+- **Description**：可选，事项描述。
+- **Category**：业务分类，用于筛选与审批条件。
+- **Amount**：金额，用于审批条件与导出。
+- **Status**：`draft` / `pending` / `approved` / `rejected` / `cancelled`。
+- **Attachment**：上传文件，存储在文件服务中。
+
+## 审批流程
+- 提交后进入 `pending` 状态，由管理员角色审批。
+- 支持撤销审批，撤销后状态为 `cancelled`。
+
+## 导入/导出
+- 导入字段：`title`, `description`, `category`, `amount`, `status`。
+- 导出包含编号、金额、审批状态等字段。
+
+## 权限
+- `example:item:view`：查看列表和详情。
+- `example:item:manage`：新建、编辑、删除、提交/撤销审批。

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

@@ -0,0 +1,32 @@
+---
+helpKey: "example/overview"
+title: "Example Module Overview"
+description: "Overview of the Example module and the platform integrations it demonstrates."
+category: "example"
+tags: ["example", "items", "approval", "import", "export", "file"]
+---
+
+# Example Module
+
+Example 模块用于演示业务模块如何接入平台能力，适合作为新模块开发的参考模板。
+
+## 覆盖能力
+- CRUD + 分页检索与筛选
+- RBAC 权限与菜单注册
+- 审批流程（提交、撤销、审批记录）
+- 导入/导出（Excel）
+- 文件上传与附件存储
+- 通知消息
+- i18n 与 Help 文档
+
+## 关键路径
+- 前端：`apps/web/src/modules/example/`
+- 后端：`apps/server/internal/modules/example/`
+
+## 相关 API
+- `GET /api/v1/example/items`
+- `POST /api/v1/example/items`
+- `PATCH /api/v1/example/items/:id`
+- `DELETE /api/v1/example/items/:id`
+- `POST /api/v1/example/items/:id/submit`
+- `POST /api/v1/example/items/:id/cancel`