@robsun/create-keystone-app 0.2.11 → 0.2.13

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

@@ -1,47 +1,47 @@
-import { lazy, Suspense, type ComponentType, type ReactElement } from 'react'
-import type { RouteObject } from 'react-router-dom'
-import { AppstoreOutlined } from '@ant-design/icons'
-import { Spin } from 'antd'
-
-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: <ExampleItemsPage />,
-    handle: {
-      menu: {
-        labelKey: 'example:menu.items',
-        icon: <AppstoreOutlined />,
-        permission: 'example:item:view',
-      },
-      breadcrumbKey: 'example:menu.items',
-      permission: 'example:item:view',
-      helpKey: 'example/items',
-    },
-  },
-].map((route) => ({
-  ...route,
-  element: route.element ? withSuspense(route.element) : route.element,
-}))
+import { lazy, Suspense, type ComponentType, type ReactElement } from 'react'
+import type { RouteObject } from 'react-router-dom'
+import { AppstoreOutlined } from '@ant-design/icons'
+import { Spin } from 'antd'
+
+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: <ExampleItemsPage />,
+    handle: {
+      menu: {
+        labelKey: 'example:menu.items',
+        icon: <AppstoreOutlined />,
+        permission: 'example:item:view',
+      },
+      breadcrumbKey: 'example:menu.items',
+      permission: 'example:item:view',
+      helpKey: 'example/items',
+    },
+  },
+].map((route) => ({
+  ...route,
+  element: route.element ? withSuspense(route.element) : route.element,
+}))

package/template/docs/CONVENTIONS.md

@@ -1,224 +1,224 @@
-# Keystone App Conventions
-
-## 目标
-- Web/Server 模块结构统一，便于复用与维护。
-- 路由、菜单、权限、帮助文档集中管理。
-- 约定优于配置，降低上手成本。
-编码规范请参考 `docs/CODE_STYLE.md`。
-
-## 项目结构
-- `apps/web/`：React + Vite 壳与业务模块。
-- `apps/server/`：Go 服务端（`cmd/server` 启动，`internal/app` 编排）。
-- `apps/server/internal/modules/`：后端模块注册与实现。
-- `apps/server/internal/frontend/`：嵌入式前端输出目录（`dist/`）。
-- `scripts/`：跨平台 dev/build/test/clean。
-- `apps/server/config.yaml`：服务端配置（支持环境变量覆盖，`docker-compose.yml` 提供依赖）。
-提示：更细节的入口说明见 `apps/web/README.md` 与 `apps/server/README.md`。
-
-## 开发流程
-- `pnpm dev`：执行 `scripts/dev.*`，检查环境并启动 Air + Vite。
-- `apps/server/.air.toml`：后端热重载配置。
-- `pnpm server:dev` 仅启动后端；`pnpm web:dev` 仅启动前端。
-
-## 配置与环境
-- `apps/server/config.yaml` 为默认配置；`apps/server/config.example.yaml` 用作模板。
-- `apps/server/config.yaml` 供 `go run`/Air 使用。
-- 前端环境变量参考 `apps/web/.env.example`（Vite 会读取）。
-- 后端环境变量需通过 Shell/工具注入（服务端不读取 `.env`）。
-- 本地数据库默认 SQLite：`apps/server/data/keystone-local.db`。
-- 本地存储目录：`apps/server/storage/`（当 `storage.driver=local`）。
-
-## 前端模块规范
-- 模块目录：`apps/web/src/modules/<module>`。
-- 在 `index.ts` 注册模块：
-```ts
-import { registerModule } from '@robsun/keystone-web-core'
-import { orderRoutes } from './routes'
-
-registerModule({ name: 'orders', routes: orderRoutes })
-```
-- 在 `routes.tsx` 配置菜单/权限/帮助：
-```tsx
-{
-  path: 'orders',
-  element: <Outlet />,
-  handle: {
-    menu: { label: 'Orders', icon: <FileTextOutlined />, permission: 'sales:order:view' },
-    breadcrumb: 'Orders',
-    permission: 'sales:order:view',
-    helpKey: 'sales/orders',
-  },
-}
-```
-- 页面放 `pages/`，组件放 `components/`，API 放 `services/`。
-
-## Help 文档
-- 文档放在 `apps/web/src/modules/<module>/help/**`。
-- `helpKey` 与路由 `handle.helpKey` 保持一致。
-- Vite 已配置 `helpDir` 扫描 `src/modules`。
-
-## 后端模块规范
-推荐结构：
-```
-apps/server/internal/modules/<module>/
-  module.go
-  api/routes/
-  api/handler/
-  domain/service/
-  infra/repository/
-  bootstrap/migrations/
-  bootstrap/seeds/
-```
-
-模块接口：
-```go
-type Module interface {
-    Name() string
-    RegisterRoutes(rg *gin.RouterGroup)
-    RegisterModels() []interface{}
-    RegisterPermissions(reg *permissions.Registry) error
-    RegisterJobs(reg *jobs.Registry) error
-    Migrate(db *gorm.DB) error
-    Seed(db *gorm.DB) error
-}
-```
-
-## 模块注册与启用
-- 在 `apps/server/internal/modules/manifest.go` 注册模块。
-- 在 `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` 注入。
-
-## 任务与队列
-- Worker 在 `cmd/server/main.go` 启动。
-- 模块通过 `RegisterJobs` 注册任务处理器。
-- 队列配置在 `apps/server/config.yaml` 的 `queue` 部分。
-
-## 嵌入式前端
-- Vite `build.outDir` 指向 `apps/server/internal/frontend/dist`。
-- Go 通过 `//go:embed` 嵌入前端产物。
-- 保留 `apps/server/internal/frontend/dist/.gitkeep`，避免 embed 找不到目录。
-
-## 多语言支持 (i18n)
-
-> 详细指南请参考 [I18N.md](./I18N.md)
-
-### 启用多语言
-在 `apps/web/src/app.config.ts` 中配置：
-```ts
-export const appConfig: Partial<KeystoneWebConfig> = {
-  // ...
-  ui: {
-    i18n: {
-      enabled: true,
-      defaultLocale: 'zh-CN',
-      supportedLocales: ['zh-CN', 'en-US'],
-    },
-  },
-}
-```
-
-### 前端模块 i18n
-1. 创建语言包目录 `modules/<module>/locales/zh-CN/*.json` 和 `en-US/*.json`
-2. 在 `modules/<module>/index.ts` 注册：
-```ts
-import { registerModule, loadModuleLocales } from '@robsun/keystone-web-core'
-
-loadModuleLocales('myModule', {
-  'zh-CN': () => import('./locales/zh-CN/myModule.json'),
-  'en-US': () => import('./locales/en-US/myModule.json'),
-})
-
-registerModule({ name: 'myModule', routes: myRoutes })
-```
-
-3. 路由配置使用 `labelKey` 和 `breadcrumbKey`：
-```tsx
-{
-  path: 'items',
-  handle: {
-    menu: {
-      label: '项目列表',          // 回退文案
-      labelKey: 'myModule:menu.items',  // i18n 键（优先）
-      icon: <AppstoreOutlined />,
-    },
-    breadcrumb: '项目列表',
-    breadcrumbKey: 'myModule:menu.items',
-  },
-}
-```
-
-4. 在组件中使用翻译：
-```tsx
-import { useTranslation } from 'react-i18next'
-
-function MyComponent() {
-  const { t } = useTranslation('myModule')
-  return <Button>{t('actions.save')}</Button>
-}
-```
-
-### 后端 i18n
-后端已内置 i18n 支持，使用 `Accept-Language` 请求头自动选择语言：
-```go
-import "your-project/infra/i18n"
-
-// 响应
-response.SuccessI18n(c, i18n.MsgCreated, data)
-response.BadRequestI18n(c, i18n.MsgInvalidRequest)
-
-// 自定义错误
-return &i18n.I18nError{Key: "order.notFound"}
-```
-
-## Testing
-- Web：`pnpm -C apps/web test`（Vitest）。
-- Server：`go -C apps/server test ./...`。
-- 全量：`pnpm test`。
+# Keystone App Conventions
+
+## 目标
+- Web/Server 模块结构统一，便于复用与维护。
+- 路由、菜单、权限、帮助文档集中管理。
+- 约定优于配置，降低上手成本。
+编码规范请参考 `docs/CODE_STYLE.md`。
+
+## 项目结构
+- `apps/web/`：React + Vite 壳与业务模块。
+- `apps/server/`：Go 服务端（`cmd/server` 启动，`internal/app` 编排）。
+- `apps/server/internal/modules/`：后端模块注册与实现。
+- `apps/server/internal/frontend/`：嵌入式前端输出目录（`dist/`）。
+- `scripts/`：跨平台 dev/build/test/clean。
+- `apps/server/config.yaml`：服务端配置（支持环境变量覆盖，`docker-compose.yml` 提供依赖）。
+提示：更细节的入口说明见 `apps/web/README.md` 与 `apps/server/README.md`。
+
+## 开发流程
+- `pnpm dev`：执行 `scripts/dev.*`，检查环境并启动 Air + Vite。
+- `apps/server/.air.toml`：后端热重载配置。
+- `pnpm server:dev` 仅启动后端；`pnpm web:dev` 仅启动前端。
+
+## 配置与环境
+- `apps/server/config.yaml` 为默认配置；`apps/server/config.example.yaml` 用作模板。
+- `apps/server/config.yaml` 供 `go run`/Air 使用。
+- 前端环境变量参考 `apps/web/.env.example`（Vite 会读取）。
+- 后端环境变量需通过 Shell/工具注入（服务端不读取 `.env`）。
+- 本地数据库默认 SQLite：`apps/server/data/keystone-local.db`。
+- 本地存储目录：`apps/server/storage/`（当 `storage.driver=local`）。
+
+## 前端模块规范
+- 模块目录：`apps/web/src/modules/<module>`。
+- 在 `index.ts` 注册模块：
+```ts
+import { registerModule } from '@robsun/keystone-web-core'
+import { orderRoutes } from './routes'
+
+registerModule({ name: 'orders', routes: orderRoutes })
+```
+- 在 `routes.tsx` 配置菜单/权限/帮助：
+```tsx
+{
+  path: 'orders',
+  element: <Outlet />,
+  handle: {
+    menu: { label: 'Orders', icon: <FileTextOutlined />, permission: 'sales:order:view' },
+    breadcrumb: 'Orders',
+    permission: 'sales:order:view',
+    helpKey: 'sales/orders',
+  },
+}
+```
+- 页面放 `pages/`，组件放 `components/`，API 放 `services/`。
+
+## Help 文档
+- 文档放在 `apps/web/src/modules/<module>/help/**`。
+- `helpKey` 与路由 `handle.helpKey` 保持一致。
+- Vite 已配置 `helpDir` 扫描 `src/modules`。
+
+## 后端模块规范
+推荐结构：
+```
+apps/server/internal/modules/<module>/
+  module.go
+  api/routes/
+  api/handler/
+  domain/service/
+  infra/repository/
+  bootstrap/migrations/
+  bootstrap/seeds/
+```
+
+模块接口：
+```go
+type Module interface {
+    Name() string
+    RegisterRoutes(rg *gin.RouterGroup)
+    RegisterModels() []interface{}
+    RegisterPermissions(reg *permissions.Registry) error
+    RegisterJobs(reg *jobs.Registry) error
+    Migrate(db *gorm.DB) error
+    Seed(db *gorm.DB) error
+}
+```
+
+## 模块注册与启用
+- 在 `apps/server/internal/modules/manifest.go` 注册模块。
+- 在 `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` 注入。
+
+## 任务与队列
+- Worker 在 `cmd/server/main.go` 启动。
+- 模块通过 `RegisterJobs` 注册任务处理器。
+- 队列配置在 `apps/server/config.yaml` 的 `queue` 部分。
+
+## 嵌入式前端
+- Vite `build.outDir` 指向 `apps/server/internal/frontend/dist`。
+- Go 通过 `//go:embed` 嵌入前端产物。
+- 保留 `apps/server/internal/frontend/dist/.gitkeep`，避免 embed 找不到目录。
+
+## 多语言支持 (i18n)
+
+> 详细指南请参考 [I18N.md](./I18N.md)
+
+### 启用多语言
+在 `apps/web/src/app.config.ts` 中配置：
+```ts
+export const appConfig: Partial<KeystoneWebConfig> = {
+  // ...
+  ui: {
+    i18n: {
+      enabled: true,
+      defaultLocale: 'zh-CN',
+      supportedLocales: ['zh-CN', 'en-US'],
+    },
+  },
+}
+```
+
+### 前端模块 i18n
+1. 创建语言包目录 `modules/<module>/locales/zh-CN/*.json` 和 `en-US/*.json`
+2. 在 `modules/<module>/index.ts` 注册：
+```ts
+import { registerModule, loadModuleLocales } from '@robsun/keystone-web-core'
+
+loadModuleLocales('myModule', {
+  'zh-CN': () => import('./locales/zh-CN/myModule.json'),
+  'en-US': () => import('./locales/en-US/myModule.json'),
+})
+
+registerModule({ name: 'myModule', routes: myRoutes })
+```
+
+3. 路由配置使用 `labelKey` 和 `breadcrumbKey`：
+```tsx
+{
+  path: 'items',
+  handle: {
+    menu: {
+      label: '项目列表',          // 回退文案
+      labelKey: 'myModule:menu.items',  // i18n 键（优先）
+      icon: <AppstoreOutlined />,
+    },
+    breadcrumb: '项目列表',
+    breadcrumbKey: 'myModule:menu.items',
+  },
+}
+```
+
+4. 在组件中使用翻译：
+```tsx
+import { useTranslation } from 'react-i18next'
+
+function MyComponent() {
+  const { t } = useTranslation('myModule')
+  return <Button>{t('actions.save')}</Button>
+}
+```
+
+### 后端 i18n
+后端已内置 i18n 支持，使用 `Accept-Language` 请求头自动选择语言：
+```go
+import "your-project/infra/i18n"
+
+// 响应
+response.SuccessI18n(c, i18n.MsgCreated, data)
+response.BadRequestI18n(c, i18n.MsgInvalidRequest)
+
+// 自定义错误
+return &i18n.I18nError{Key: "order.notFound"}
+```
+
+## Testing
+- Web：`pnpm -C apps/web test`（Vitest）。
+- Server：`go -C apps/server test ./...`。
+- 全量：`pnpm test`。

package/template/package.json

@@ -1,27 +1,27 @@
-{
-  "name": "__APP_NAME__",
-  "private": true,
-  "version": "0.1.0",
-  "scripts": {
-    "dev": "node scripts/dev.js",
-    "build": "node scripts/build.js",
-    "build:web": "pnpm --filter web build",
-    "check-modules": "node scripts/check-modules.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",
-    "web:dev": "pnpm -C apps/web dev",
-    "server:dev": "go -C apps/server run ./cmd/server",
-    "generate:i18n-types": "node scripts/generate-i18n-types.js",
-    "prepare": "husky"
-  },
-  "devDependencies": {
-    "husky": "^9.1.7",
-    "lint-staged": "^16.2.7",
-    "prettier": "^3.7.4",
-    "yaml": "^2.4.5"
-  },
-  "packageManager": "pnpm@9.15.0"
-}
+{
+  "name": "__APP_NAME__",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "node scripts/dev.js",
+    "build": "node scripts/build.js",
+    "build:web": "pnpm --filter web build",
+    "check-modules": "node scripts/check-modules.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",
+    "web:dev": "pnpm -C apps/web dev",
+    "server:dev": "go -C apps/server run ./cmd/server",
+    "generate:i18n-types": "node scripts/generate-i18n-types.js",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "yaml": "^2.4.5"
+  },
+  "packageManager": "pnpm@9.15.0"
+}