@robsun/create-keystone-app 0.2.15 → 0.4.1

package/template/.codex/skills/keystone-dev/references/TESTING.md

@@ -1,44 +0,0 @@
-# Keystone 开发测试清单
-
-## 快速入口
-- 仓库根目录：`pnpm test`（模板测试 + `go test ./...`）
-- 仅 Go：`go test ./...`
-- 模板项目：`pnpm -C packages/create-keystone-app/template test`
-
-## 按改动范围选择
-后端（api/domain/infra/bootstrap/server）
-- `go test ./...`
-- 若改动较大可补 `go vet ./...`
-
-模板前端（packages/create-keystone-app/template/apps/web）
-- `pnpm -C packages/create-keystone-app/template/apps/web typecheck`
-- `pnpm -C packages/create-keystone-app/template/apps/web lint`
-- `pnpm -C packages/create-keystone-app/template/apps/web test`
-
-前端核心包（packages/keystone-web-core）
-- `pnpm -C packages/keystone-web-core build`
-
-脚手架/模板变更
-- `pnpm scaffold:verify`
-
-合同变更
-- `pnpm contracts:check`
-- 如更新了合同内容，执行 `pnpm contracts:sync`
-
-## 写测试（必做）
-后端
-- 领域/服务逻辑新增或改动：在 `tests/unit/platform/service` 或对应 domain 下补单测。
-- Repository 变更：在 `tests/unit/platform/repository` 补单测。
-- 新增/调整 API：在 `tests/integration/platform/api` 补集成测试。
-- 参考用例：`tests/unit/platform/approval/service_test.go`、`tests/integration/platform/api/approval_schema_test.go`。
-
-前端（模板 web）
-- 新增页面/交互：在 `packages/create-keystone-app/template/apps/web/tests` 新增 `*.test.tsx`。
-- 使用 vitest + Testing Library（已在 `vite.config.ts` 配好 test 配置）。
-
-前端核心包（keystone-web-core）
-- 新增核心组件/逻辑：优先在模板 web 侧写集成测试覆盖。
-- 如必须在包内写单测，需要补齐包内测试配置后再添加用例。
-
-## 最小通过标准
-- 单点改动跑对应子项；跨域改动直接跑 `pnpm test`。

package/template/apps/server/internal/app/routes/module_routes.go

@@ -1,16 +0,0 @@
-package routes
-
-import (
-	"github.com/gin-gonic/gin"
-
-	"github.com/robsuncn/keystone/bootstrap/config"
-
-	"__APP_NAME__/apps/server/internal/modules"
-)
-
-func registerModuleRoutes(v1 *gin.RouterGroup, cfg *config.Config) {
-	if v1 == nil || cfg == nil {
-		return
-	}
-	modules.LoadEnabled(cfg.Modules.Enabled, v1)
-}

package/template/apps/server/internal/app/routes/routes.go

@@ -1,226 +0,0 @@
-package routes
-
-import (
-	"log"
-	"time"
-
-	"github.com/gin-gonic/gin"
-	swaggerFiles "github.com/swaggo/files"
-	ginSwagger "github.com/swaggo/gin-swagger"
-	"gorm.io/gorm"
-
-	"github.com/robsuncn/keystone/api/handler/audit"
-	"github.com/robsuncn/keystone/api/handler/auth"
-	"github.com/robsuncn/keystone/api/handler/files"
-	"github.com/robsuncn/keystone/api/handler/health"
-	jobHandlers "github.com/robsuncn/keystone/api/handler/jobs"
-	"github.com/robsuncn/keystone/api/handler/notifications"
-	"github.com/robsuncn/keystone/api/handler/org"
-	"github.com/robsuncn/keystone/api/handler/rbac"
-	"github.com/robsuncn/keystone/api/handler/settings"
-	"github.com/robsuncn/keystone/api/handler/tenant"
-	"github.com/robsuncn/keystone/api/handler/user"
-	"github.com/robsuncn/keystone/api/middleware"
-	coreRoutes "github.com/robsuncn/keystone/api/routes"
-	"github.com/robsuncn/keystone/bootstrap/config"
-	approvalHandler "github.com/robsuncn/keystone/domain/approval/handler"
-	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"
-	jobInfra "github.com/robsuncn/keystone/infra/jobs"
-	"github.com/robsuncn/keystone/infra/queue"
-	"github.com/robsuncn/keystone/infra/repository"
-	"github.com/robsuncn/keystone/infra/storage"
-
-	"__APP_NAME__/apps/server/docs"
-	"__APP_NAME__/apps/server/internal/frontend"
-)
-
-// SetupRouter wires repositories, services, handlers and registers routes.
-func SetupRouter(cfg *config.Config, db *gorm.DB, jobQueue queue.Queue) *gin.Engine {
-	r := gin.New()
-	r.Use(gin.Logger(), gin.Recovery())
-
-	if cfg != nil && cfg.Server.SwaggerEnabled {
-		docs.SwaggerInfo.BasePath = "/api/v1"
-		r.GET("/api/docs/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
-	}
-
-	userRepo := repository.NewUserRepository(db)
-	userProfileRepo := repository.NewUserProfileRepository(db)
-	userInvitationRepo := repository.NewUserInvitationRepository(db)
-	platformUserRepo := repository.NewPlatformUserRepository(db)
-	roleRepo := repository.NewRoleRepository(db)
-	permRepo := repository.NewPermissionRepository(db)
-	dataScopeRepo := repository.NewDataScopePolicyRepository(db)
-	loginLogRepo := repository.NewLoginLogRepository(db)
-	blacklistRepo := repository.NewTokenBlacklistRepository(db)
-	auditLogRepo := repository.NewAuditLogRepository(db)
-	tenantRepo := repository.NewTenantRepository(db)
-	departmentRepo := repository.NewDepartmentRepository(db)
-	membershipRepo := repository.NewMembershipRepository(db)
-	settingRepo := repository.NewSettingRepository(db)
-	notificationRepo := repository.NewNotificationRepository(db)
-	jobRepo := repository.NewJobRepository(db)
-
-	approvalFlowRepo := approvalRepo.NewFlowRepository(db)
-	approvalNodeRepo := approvalRepo.NewNodeRepository(db)
-	approvalInstanceRepo := approvalRepo.NewInstanceRepository(db)
-	approvalRecordRepo := approvalRepo.NewRecordRepository(db)
-
-	permSvc := service.NewPermissionService(permRepo, userRepo)
-	platformPermSvc := service.NewPlatformPermissionService(platformUserRepo)
-	roleSvc := service.NewRoleService(roleRepo)
-	userSvc := service.NewUserService(userRepo, roleRepo, blacklistRepo)
-	tenantSvc := service.NewTenantService(db, tenantRepo, userRepo, roleRepo)
-	authSvc := service.NewAuthService(userRepo, roleRepo, blacklistRepo, loginLogRepo, cfg.JWT).
-		WithTenantRepository(tenantRepo)
-	platformAuthSvc := service.NewPlatformAuthService(platformUserRepo, blacklistRepo, loginLogRepo, cfg.JWT)
-	loginLogSvc := service.NewLoginLogService(loginLogRepo)
-	auditLogSvc := service.NewAuditLogService(db, auditLogRepo)
-	departmentSvc := service.NewDepartmentService(db, departmentRepo, membershipRepo)
-	membershipSvc := service.NewMembershipService(db, membershipRepo, departmentRepo)
-	profileSvc := service.NewUserProfileService(userRepo, userProfileRepo)
-	invitationSvc := service.NewUserInvitationService(userInvitationRepo)
-	settingSvc := service.NewSettingService(db, settingRepo)
-	prefixSvc := service.NewSettingPrefixService(settingSvc)
-	notificationSvc := service.NewNotificationService(db, notificationRepo)
-	jobSvc := service.NewJobService(db, jobRepo)
-
-	policySvc := permissions.NewPolicyService(dataScopeRepo)
-	evaluator := permissions.NewEvaluator(departmentSvc)
-	enforcer := permissions.NewEnforcer(policySvc, evaluator, userRepo)
-
-	approvalService := approvalSvc.NewService(
-		db,
-		approvalInstanceRepo,
-		approvalFlowRepo,
-		approvalNodeRepo,
-		approvalRecordRepo,
-		userRepo,
-		permSvc,
-		nil,
-	)
-	auditRecorder := service.NewAuditLogRecorder(auditLogSvc, userRepo)
-	approvalService.WithAuditRecorder(approvalSvc.NewAuditRecorderAdapter(auditRecorder))
-
-	healthHandler := health.NewHealthHandler(db, nil)
-	authHandler := auth.NewAuthHandler(authSvc)
-	platformAuthHandler := auth.NewPlatformAuthHandler(platformAuthSvc)
-	tenantHandler := tenant.NewTenantHandler(tenantSvc)
-	userHandler := user.NewUserHandler(userSvc, departmentSvc, invitationSvc, profileSvc)
-	roleHandler := rbac.NewRoleHandler(roleSvc, permSvc, policySvc)
-	permissionHandler := rbac.NewPermissionHandler(permSvc)
-	loginLogHandler := audit.NewLoginLogHandler(loginLogSvc)
-	auditLogHandler := audit.NewAuditLogHandler(auditLogSvc)
-	departmentHandler := org.NewDepartmentHandler(departmentSvc)
-	membershipHandler := org.NewMembershipHandler(membershipSvc)
-	systemSettingsHandler := settings.NewSystemSettingsHandler(settingSvc).WithPrefixSettings(prefixSvc)
-	notificationHandler := notifications.NewNotificationHandler(notificationSvc)
-	jobHandler := jobHandlers.NewJobHandler(jobSvc)
-
-	approvalSchemaHandler := approvalHandler.NewSchemaHandler()
-	approvalFlowHandler := approvalHandler.NewFlowHandler(db, approvalFlowRepo, approvalNodeRepo, approvalInstanceRepo)
-	approvalNodeHandler := approvalHandler.NewNodeHandler(approvalNodeRepo, approvalFlowRepo)
-	approvalInstanceHandler := approvalHandler.NewInstanceHandler(
-		approvalService,
-		approvalInstanceRepo,
-		approvalRecordRepo,
-		approvalFlowRepo,
-		approvalNodeRepo,
-		userRepo,
-		enforcer,
-		nil,
-	)
-	approvalWorkbenchHandler := approvalHandler.NewWorkbenchHandler(
-		approvalService,
-		approvalInstanceRepo,
-		approvalRecordRepo,
-		approvalFlowRepo,
-		userRepo,
-		enforcer,
-		nil,
-	)
-	approvalRecordHandler := approvalHandler.NewRecordHandler(
-		approvalRecordRepo,
-		approvalFlowRepo,
-		userRepo,
-		enforcer,
-		nil,
-	)
-
-	var fileHandler *files.FileHandler
-	storageSvc, err := storage.New(cfg.Storage)
-	if err != nil {
-		log.Printf("storage init failed: %v", err)
-	} else {
-		fileHandler = files.NewFileHandler(storageSvc)
-	}
-
-	var dispatcher *jobInfra.Dispatcher
-	var importHandler *jobHandlers.ImportHandler
-	var exportHandler *jobHandlers.ExportHandler
-	if jobQueue != nil {
-		dispatcher = jobInfra.NewDispatcher(jobQueue, jobSvc)
-	}
-	if dispatcher != nil {
-		importHandler = jobHandlers.NewImportHandler(dispatcher)
-		exportHandler = jobHandlers.NewExportHandler(dispatcher)
-	}
-
-	authMiddleware := middleware.NewAuthMiddleware(cfg.JWT, blacklistRepo, userRepo)
-	rbacMiddleware := middleware.NewRBACMiddleware(permSvc)
-	platformAuthMiddleware := middleware.NewPlatformAuthMiddleware(cfg.JWT, blacklistRepo, platformUserRepo)
-	platformRBACMiddleware := middleware.NewRBACMiddleware(platformPermSvc)
-	tenantGuards := []gin.HandlerFunc{
-		middleware.RequireTenant(),
-		middleware.NewTenantStatusMiddleware(tenantSvc),
-		middleware.NewTenantRLSMiddleware(db),
-	}
-	authRateLimiter := middleware.NewRateLimiter(20, time.Minute)
-
-	v1 := r.Group("/api/v1")
-	coreRoutes.RegisterCoreRoutes(v1, coreRoutes.CoreRouteDeps{
-		HealthHandler:         healthHandler,
-		AuthMiddleware:        authMiddleware,
-		PlatformAuth:          platformAuthMiddleware,
-		PlatformRBAC:          platformRBACMiddleware,
-		TenantGuards:          tenantGuards,
-		RBAC:                  rbacMiddleware,
-		AuthHandler:           authHandler,
-		PlatformAuthHandler:   platformAuthHandler,
-		TenantHandler:         tenantHandler,
-		AuthRateLimiter:       authRateLimiter,
-		UserHandler:           userHandler,
-		RoleHandler:           roleHandler,
-		PermissionHandler:     permissionHandler,
-		LoginLogHandler:       loginLogHandler,
-		AuditLogHandler:       auditLogHandler,
-		FileHandler:           fileHandler,
-		DepartmentHandler:     departmentHandler,
-		MembershipHandler:     membershipHandler,
-		ApprovalSchema:        approvalSchemaHandler,
-		ApprovalFlow:          approvalFlowHandler,
-		ApprovalNode:          approvalNodeHandler,
-		ApprovalInstance:      approvalInstanceHandler,
-		ApprovalWorkbench:     approvalWorkbenchHandler,
-		ApprovalRecord:        approvalRecordHandler,
-		NotificationHandler:   notificationHandler,
-		JobHandler:            jobHandler,
-		ImportHandler:         importHandler,
-		ExportHandler:         exportHandler,
-		SystemSettingsHandler: systemSettingsHandler,
-	})
-	registerModuleRoutes(v1, cfg)
-
-	spaHandler, err := frontend.NewSPAHandler()
-	if err == nil {
-		r.NoRoute(spaHandler.GinHandler())
-		log.Println("Frontend: embedded SPA handler enabled")
-	} else if cfg != nil && cfg.Server.Mode == "release" {
-		log.Printf("Warning: frontend not available: %v", err)
-	}
-
-	return r
-}

package/template/apps/server/internal/app/startup/startup.go

@@ -1,74 +0,0 @@
-package startup
-
-import (
-	"fmt"
-	"log"
-	"time"
-
-	"gorm.io/gorm"
-
-	"github.com/robsuncn/keystone/bootstrap/config"
-	"github.com/robsuncn/keystone/bootstrap/migrations"
-	"github.com/robsuncn/keystone/bootstrap/seeds"
-	"github.com/robsuncn/keystone/domain/permissions"
-
-	"__APP_NAME__/apps/server/internal/modules"
-)
-
-// InitializeDatabase runs base + module migrations and seeds.
-func InitializeDatabase(cfg *config.Config) (*gorm.DB, error) {
-	if cfg == nil {
-		return nil, fmt.Errorf("config is nil")
-	}
-
-	dbCfg := &cfg.Database
-	start := time.Now()
-	log.Println("========================================")
-	log.Println("Keystone Database Initialization")
-	log.Println("========================================")
-
-	log.Printf("[startup] Connecting to database (driver: %s)...", dbCfg.Driver)
-	db, err := config.InitDB(dbCfg, cfg.Server.Mode)
-	if err != nil {
-		return nil, fmt.Errorf("database connection failed: %w", err)
-	}
-
-	log.Println("[startup] Phase 1: Auth model migration...")
-	if err := config.MigrateDB(db, config.AuthModels()...); err != nil {
-		return nil, fmt.Errorf("auth model migration failed: %w", err)
-	}
-
-	log.Println("[startup] Phase 2: Platform schema migrations...")
-	if err := migrations.RunAll(db); err != nil {
-		return nil, fmt.Errorf("platform migrations failed: %w", err)
-	}
-
-	log.Println("[startup] Phase 3: Module schema migrations...")
-	if err := modules.MigrateEnabled(cfg.Modules.Enabled, db); err != nil {
-		return nil, fmt.Errorf("module migrations failed: %w", err)
-	}
-
-	log.Println("[startup] Phase 4: Data seeding...")
-	if err := seeds.RunAll(db, seeds.Options{
-		RegisterPermissions: func(reg *permissions.Registry) error {
-			return modules.RegisterPermissions(cfg.Modules.Enabled, reg)
-		},
-	}); err != nil {
-		return nil, fmt.Errorf("data seeding failed: %w", err)
-	}
-	if err := modules.SeedEnabled(cfg.Modules.Enabled, db); err != nil {
-		return nil, fmt.Errorf("module seeding failed: %w", err)
-	}
-
-	log.Println("[startup] Phase 5: Security policies...")
-	if err := migrations.MigrateTenantRLS(db); err != nil {
-		return nil, fmt.Errorf("RLS setup failed: %w", err)
-	}
-
-	elapsed := time.Since(start).Round(time.Millisecond)
-	log.Println("========================================")
-	log.Printf("Database initialization complete (%v)", elapsed)
-	log.Println("========================================")
-
-	return db, nil
-}

package/template/apps/server/internal/frontend/handler.go

@@ -1,122 +0,0 @@
-package frontend
-
-import (
-	"io"
-	"net/http"
-	"path"
-	"strings"
-
-	"github.com/gin-gonic/gin"
-)
-
-// SPAHandler serves the embedded frontend files with SPA route fallback.
-type SPAHandler struct {
-	fs         http.FileSystem
-	fileServer http.Handler
-	indexHTML  []byte
-}
-
-// NewSPAHandler creates a new SPA handler with the embedded file system.
-func NewSPAHandler() (*SPAHandler, error) {
-	fsys, err := GetFileSystem()
-	if err != nil {
-		return nil, err
-	}
-
-	handler := &SPAHandler{
-		fs:         fsys,
-		fileServer: http.FileServer(fsys),
-	}
-
-	if err := handler.loadIndex(); err != nil {
-		return nil, err
-	}
-
-	return handler, nil
-}
-
-func (h *SPAHandler) loadIndex() error {
-	file, err := h.fs.Open("/index.html")
-	if err != nil {
-		return err
-	}
-	defer file.Close()
-
-	h.indexHTML, err = io.ReadAll(file)
-	if err != nil {
-		return err
-	}
-
-	return nil
-}
-
-// ServeHTTP implements http.Handler for the SPA.
-func (h *SPAHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
-	urlPath := path.Clean(r.URL.Path)
-
-	if urlPath == "/" || urlPath == "" {
-		h.serveIndex(w)
-		return
-	}
-
-	file, err := h.fs.Open(urlPath)
-	if err != nil {
-		h.serveIndex(w)
-		return
-	}
-	defer file.Close()
-
-	stat, err := file.Stat()
-	if err != nil || stat.IsDir() {
-		h.serveIndex(w)
-		return
-	}
-
-	h.setContentType(w, urlPath)
-	h.fileServer.ServeHTTP(w, r)
-}
-
-func (h *SPAHandler) serveIndex(w http.ResponseWriter) {
-	w.Header().Set("Content-Type", "text/html; charset=utf-8")
-	w.Header().Set("Cache-Control", "no-cache, no-store, must-revalidate")
-	w.WriteHeader(http.StatusOK)
-	w.Write(h.indexHTML)
-}
-
-func (h *SPAHandler) setContentType(w http.ResponseWriter, filePath string) {
-	ext := strings.ToLower(path.Ext(filePath))
-	contentTypes := map[string]string{
-		".html":  "text/html; charset=utf-8",
-		".js":    "application/javascript; charset=utf-8",
-		".mjs":   "application/javascript; charset=utf-8",
-		".css":   "text/css; charset=utf-8",
-		".json":  "application/json; charset=utf-8",
-		".svg":   "image/svg+xml",
-		".png":   "image/png",
-		".jpg":   "image/jpeg",
-		".jpeg":  "image/jpeg",
-		".gif":   "image/gif",
-		".webp":  "image/webp",
-		".ico":   "image/x-icon",
-		".woff":  "font/woff",
-		".woff2": "font/woff2",
-		".ttf":   "font/ttf",
-		".eot":   "application/vnd.ms-fontobject",
-		".map":   "application/json",
-	}
-
-	if ct, ok := contentTypes[ext]; ok {
-		w.Header().Set("Content-Type", ct)
-	}
-
-	if strings.Contains(filePath, "/assets/") {
-		w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
-	}
-}
-
-// GinHandler returns a gin.HandlerFunc for router.NoRoute().
-func (h *SPAHandler) GinHandler() gin.HandlerFunc {
-	return func(c *gin.Context) {
-		h.ServeHTTP(c.Writer, c.Request)
-	}
-}

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

@@ -1,145 +0,0 @@
-package modules
-
-import (
-	"sync"
-
-	"github.com/gin-gonic/gin"
-	"gorm.io/gorm"
-
-	"github.com/robsuncn/keystone/domain/permissions"
-	"github.com/robsuncn/keystone/infra/jobs"
-)
-
-// Module registers routes and lifecycle hooks for a business module.
-type Module interface {
-	Name() string
-	RegisterRoutes(rg *gin.RouterGroup)
-	RegisterModels() []interface{}
-	RegisterPermissions(registry *permissions.Registry) error
-	RegisterJobs(registry *jobs.Registry) error
-	Migrate(db *gorm.DB) error
-	Seed(db *gorm.DB) error
-}
-
-var (
-	registryMu sync.RWMutex
-	registry   = make(map[string]Module)
-	order      []string
-)
-
-// Register adds or replaces a module by name.
-func Register(module Module) {
-	if module == nil {
-		return
-	}
-	name := module.Name()
-	if name == "" {
-		return
-	}
-	registryMu.Lock()
-	defer registryMu.Unlock()
-	if _, ok := registry[name]; !ok {
-		order = append(order, name)
-	}
-	registry[name] = module
-}
-
-// Clear removes all registered modules.
-func Clear() {
-	registryMu.Lock()
-	defer registryMu.Unlock()
-	registry = make(map[string]Module)
-	order = nil
-}
-
-// Registered returns a snapshot of the current modules.
-func Registered() []Module {
-	registryMu.RLock()
-	defer registryMu.RUnlock()
-	out := make([]Module, 0, len(order))
-	for _, name := range order {
-		if module, ok := registry[name]; ok {
-			out = append(out, module)
-		}
-	}
-	return out
-}
-
-func enabledModules(enabled []string) []Module {
-	if len(enabled) == 0 {
-		return nil
-	}
-	registryMu.RLock()
-	defer registryMu.RUnlock()
-	out := make([]Module, 0, len(enabled))
-	for _, name := range enabled {
-		module, ok := registry[name]
-		if !ok || module == nil {
-			continue
-		}
-		out = append(out, module)
-	}
-	return out
-}
-
-// LoadEnabled registers enabled module routes.
-func LoadEnabled(enabled []string, rg *gin.RouterGroup) {
-	if len(enabled) == 0 || rg == nil {
-		return
-	}
-	for _, module := range enabledModules(enabled) {
-		module.RegisterRoutes(rg)
-	}
-}
-
-// RegisterPermissions registers permission definitions for enabled modules.
-func RegisterPermissions(enabled []string, reg *permissions.Registry) error {
-	if len(enabled) == 0 || reg == nil {
-		return nil
-	}
-	for _, module := range enabledModules(enabled) {
-		if err := module.RegisterPermissions(reg); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-// RegisterJobs registers job handlers for enabled modules.
-func RegisterJobs(enabled []string, reg *jobs.Registry) error {
-	if len(enabled) == 0 || reg == nil {
-		return nil
-	}
-	for _, module := range enabledModules(enabled) {
-		if err := module.RegisterJobs(reg); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-// MigrateEnabled runs migrations for enabled modules.
-func MigrateEnabled(enabled []string, db *gorm.DB) error {
-	if len(enabled) == 0 || db == nil {
-		return nil
-	}
-	for _, module := range enabledModules(enabled) {
-		if err := module.Migrate(db); err != nil {
-			return err
-		}
-	}
-	return nil
-}
-
-// SeedEnabled runs seed data setup for enabled modules.
-func SeedEnabled(enabled []string, db *gorm.DB) error {
-	if len(enabled) == 0 || db == nil {
-		return nil
-	}
-	for _, module := range enabledModules(enabled) {
-		if err := module.Seed(db); err != nil {
-			return err
-		}
-	}
-	return nil
-}

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

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

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