@robsun/create-keystone-app 0.2.13 → 0.4.0

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

@@ -1,19 +1,71 @@
-import { api, type ApiResponse } from '@robsun/keystone-web-core'
-import type { ExampleItem, ExampleItemStatus } from '../types'
+import { api, type ApiResponse, type PaginatedData } from '@robsun/keystone-web-core'
+import type {
+  ExampleApprovalStatus,
+  ExampleItem,
+  ExampleItemCategory,
+  ExampleItemStatus,
+} from '../types'
 
-type ItemListResponse = {
-  items: ExampleItem[]
+export type ExampleItemListParams = {
+  page?: number
+  pageSize?: number
+  keyword?: string
+  status?: ExampleItemStatus
+  approvalStatus?: ExampleApprovalStatus
+  category?: ExampleItemCategory
+  startDate?: string
+  endDate?: string
+}
+
+export type ExampleItemExportParams = Omit<ExampleItemListParams, 'page' | 'pageSize'>
+
+export const listExampleItems = async (
+  params: ExampleItemListParams = {}
+): Promise<PaginatedData<ExampleItem>> => {
+  const { data } = await api.get<ApiResponse<PaginatedData<ExampleItem>>>('/example/items', {
+    params: {
+      page: params.page,
+      page_size: params.pageSize,
+      keyword: params.keyword,
+      status: params.status,
+      approval_status: params.approvalStatus,
+      category: params.category,
+      start_date: params.startDate,
+      end_date: params.endDate,
+    },
+  })
+  return data.data
+}
+
+export const exportExampleItemsPdf = async (
+  params: ExampleItemExportParams = {}
+): Promise<Blob> => {
+  const { data } = await api.get<Blob>('/example/items/export/pdf', {
+    params: {
+      keyword: params.keyword,
+      status: params.status,
+      approval_status: params.approvalStatus,
+      category: params.category,
+      start_date: params.startDate,
+      end_date: params.endDate,
+    },
+    responseType: 'blob',
+  })
+  return data
 }
 
-export const listExampleItems = async () => {
-  const { data } = await api.get<ApiResponse<ItemListResponse>>('/example/items')
-  return data.data.items
+export const getExampleItem = async (id: number): Promise<ExampleItem> => {
+  const { data } = await api.get<ApiResponse<ExampleItem>>(`/example/items/${id}`)
+  return data.data
 }
 
 export const createExampleItem = async (payload: {
   title: string
   description?: string
+  category?: ExampleItemCategory
+  amount?: number
   status?: ExampleItemStatus
+  attachment?: Record<string, unknown> | null
 }) => {
   const { data } = await api.post<ApiResponse<ExampleItem>>('/example/items', payload)
   return data.data
@@ -21,7 +73,14 @@ export const createExampleItem = async (payload: {
 
 export const updateExampleItem = async (
   id: number,
-  payload: { title?: string; description?: string; status?: ExampleItemStatus }
+  payload: {
+    title?: string
+    description?: string
+    category?: ExampleItemCategory
+    amount?: number
+    status?: ExampleItemStatus
+    attachment?: Record<string, unknown> | null
+  }
 ) => {
   const { data } = await api.patch<ApiResponse<ExampleItem>>(`/example/items/${id}`, payload)
   return data.data
@@ -30,3 +89,15 @@ export const updateExampleItem = async (
 export const deleteExampleItem = async (id: number) => {
   await api.delete<ApiResponse<{ id: number }>>(`/example/items/${id}`)
 }
+
+export const submitExampleItem = async (id: number) => {
+  const { data } = await api.post<ApiResponse<ExampleItem>>(`/example/items/${id}/submit`)
+  return data.data
+}
+
+export const cancelExampleItem = async (id: number, reason?: string) => {
+  const { data } = await api.post<ApiResponse<ExampleItem>>(`/example/items/${id}/cancel`, {
+    reason,
+  })
+  return data.data
+}

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

@@ -1,10 +1,23 @@
-export type ExampleItemStatus = 'active' | 'inactive'
+import type { UploadedFile } from '@robsun/keystone-web-core'
+
+export type ExampleItemStatus = 'draft' | 'pending' | 'approved' | 'rejected' | 'cancelled'
+
+export type ExampleItemCategory = 'general' | 'operations' | 'finance' | 'growth'
+
+export type ExampleApprovalStatus = 'pending' | 'approved' | 'rejected' | 'cancelled'
 
 export interface ExampleItem {
   id: number
+  number: string
   title: string
   description: string
+  category: ExampleItemCategory
+  amount: number
   status: ExampleItemStatus
+  approval_instance_id?: number
+  approval_status?: ExampleApprovalStatus
+  reject_reason?: string
+  attachment?: UploadedFile | null
   created_at: string
   updated_at: string
 }

package/template/apps/web/src/modules/index.ts

@@ -0,0 +1 @@
+// Register application modules here.

package/template/apps/web/vite.config.ts

@@ -1,12 +1,18 @@
 /// <reference types="vitest" />
 import { createKeystoneViteConfig } from '@robsun/keystone-web-core/vite'
 import path from 'path'
+import { fileURLToPath } from 'url'
+
+const rootDir = path.dirname(fileURLToPath(import.meta.url))
 
 export default createKeystoneViteConfig({
-  helpDir: path.resolve(__dirname, './src/modules'),
+  root: rootDir,
+  helpExtraDirs: [path.resolve(rootDir, './src/modules')],
+  helpLocales: ['zh-CN', 'en-US'],
+  helpDefaultLocale: 'zh-CN',
   resolve: {
     alias: {
-      '@app': path.resolve(__dirname, './src'),
+      '@app': path.resolve(rootDir, './src'),
     },
   },
   server: {
@@ -19,7 +25,7 @@ export default createKeystoneViteConfig({
     },
   },
   build: {
-    outDir: path.resolve(__dirname, '../server/internal/frontend/dist'),
+    outDir: path.resolve(rootDir, '../server/internal/frontend/dist'),
     emptyOutDir: false,
     sourcemap: true,
     rollupOptions: {

package/template/docs/CONVENTIONS.md

@@ -16,9 +16,11 @@
 提示：更细节的入口说明见 `apps/web/README.md` 与 `apps/server/README.md`。
 
 ## 开发流程
+- 先写/补测试：后端用 `*_test.go`，前端用 `*.test.tsx`/`*.spec.tsx`，覆盖核心逻辑与关键路径。
 - `pnpm dev`：执行 `scripts/dev.*`，检查环境并启动 Air + Vite。
 - `apps/server/.air.toml`：后端热重载配置。
-- `pnpm server:dev` 仅启动后端；`pnpm web:dev` 仅启动前端。
+- `pnpm server:dev` 仅启动后端；`pnpm -C apps/web dev` 仅启动前端。
+- 开发完成运行测试：`pnpm test` 或 `pnpm -C apps/web test` + `go -C apps/server test ./...`。
 
 ## 配置与环境
 - `apps/server/config.yaml` 为默认配置；`apps/server/config.example.yaml` 用作模板。
@@ -52,10 +54,10 @@ registerModule({ name: 'orders', routes: orderRoutes })
 ```
 - 页面放 `pages/`，组件放 `components/`，API 放 `services/`。
 
-## Help 文档
-- 文档放在 `apps/web/src/modules/<module>/help/**`。
-- `helpKey` 与路由 `handle.helpKey` 保持一致。
-- Vite 已配置 `helpDir` 扫描 `src/modules`。
+## Help 文档
+- 文档放在 `apps/web/src/modules/<module>/help/<locale>/**`。
+- `helpKey` 与路由 `handle.helpKey` 保持一致。
+- Vite 默认合并 core 帮助与 `src/modules`（`helpExtraDirs`），并按语言目录加载。
 
 ## 后端模块规范
 推荐结构：
@@ -77,7 +79,7 @@ type Module interface {
     RegisterRoutes(rg *gin.RouterGroup)
     RegisterModels() []interface{}
     RegisterPermissions(reg *permissions.Registry) error
-    RegisterJobs(reg *jobs.Registry) error
+    RegisterTasks(reg *scheduler.Registry) error
     Migrate(db *gorm.DB) error
     Seed(db *gorm.DB) error
 }
@@ -138,7 +140,7 @@ RegisterPermissions 负责定义权限种子与后台管理项
 
 ## 任务与队列
 - Worker 在 `cmd/server/main.go` 启动。
-- 模块通过 `RegisterJobs` 注册任务处理器。
+- 模块通过 `RegisterTasks` 注册任务处理器。
 - 队列配置在 `apps/server/config.yaml` 的 `queue` 部分。
 
 ## 嵌入式前端
@@ -222,3 +224,4 @@ return &i18n.I18nError{Key: "order.notFound"}
 - Web：`pnpm -C apps/web test`（Vitest）。
 - Server：`go -C apps/server test ./...`。
 - 全量：`pnpm test`。
+- 测试目录：`tests/unit`、`tests/integration`、`tests/perf`（或包内 `*_test.go`）。

package/template/package.json

@@ -2,18 +2,17 @@
   "name": "__APP_NAME__",
   "private": true,
   "version": "0.1.0",
-  "scripts": {
-    "dev": "node scripts/dev.js",
+  "scripts": {
+    "dev": "node scripts/dev.js",
+    "server:dev": "go -C apps/server run ./cmd/server",
     "build": "node scripts/build.js",
     "build:web": "pnpm --filter web build",
-    "check-modules": "node scripts/check-modules.js",
+    "check-modules": "node scripts/check-modules.js && node scripts/check-help.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"
   },

package/template/pnpm-lock.yaml

@@ -27,20 +27,26 @@ importers:
         specifier: ^6.1.0
         version: 6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@robsun/keystone-web-core':
-        specifier: 0.1.9
-        version: 0.1.9(@ant-design/icons@6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@types/react@19.2.7)(antd@6.1.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react-dom@19.2.3(react@19.2.3))(react-router-dom@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react@19.2.3)(use-sync-external-store@1.6.0(react@19.2.3))(vite@7.3.0(@types/node@24.10.4)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2))
+        specifier: ^0.3.0
+        version: 0.3.0(@ant-design/icons@6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@types/react@19.2.7)(antd@6.1.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react-dom@19.2.3(react@19.2.3))(react-router-dom@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react@19.2.3)(typescript@5.9.3)(use-sync-external-store@1.6.0(react@19.2.3))(vite@7.3.0(@types/node@24.10.4)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2))
       antd:
         specifier: ^6.0.1
         version: 6.1.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       dayjs:
         specifier: ^1.11.19
         version: 1.11.19
+      i18next:
+        specifier: ^24.2.3
+        version: 24.2.3(typescript@5.9.3)
       react:
         specifier: ^19.2.0
         version: 19.2.3
       react-dom:
         specifier: ^19.2.0
         version: 19.2.3(react@19.2.3)
+      react-i18next:
+        specifier: ^15.5.1
+        version: 15.7.4(i18next@24.2.3(typescript@5.9.3))(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(typescript@5.9.3)
       react-router-dom:
         specifier: ^7.10.1
         version: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
@@ -924,8 +930,8 @@ packages:
       react: '>=16.9.0'
       react-dom: '>=16.9.0'
 
-  '@robsun/keystone-web-core@0.1.9':
-    resolution: {integrity: sha512-zbN6yiq3p/wwVOZvGj5YI6lT+xXCyWx87QIsM3IXnNyMxJl4OLRvv1xXN3u6K4uQpp2q+no4CeYLAfRwFIKNNw==}
+  '@robsun/keystone-web-core@0.3.0':
+    resolution: {integrity: sha512-BFJehFDaAv62gtoBEw1BhgeYRbyz/LIOKM5tlIZSR8IxlwxagNBiGywwP+gX+93HQRbM6+3aT4EZkDzi4T7r4g==}
     peerDependencies:
       '@ant-design/icons': ^6.1.0
       antd: ^6.0.1
@@ -1912,6 +1918,9 @@ packages:
     resolution: {integrity: sha512-Y22oTqIU4uuPgEemfz7NDJz6OeKf12Lsu+QC+s3BVpda64lTiMYCyGwg5ki4vFxkMwQdeZDl2adZoqUgdFuTgQ==}
     engines: {node: '>=18'}
 
+  html-parse-stringify@3.0.1:
+    resolution: {integrity: sha512-KknJ50kTInJ7qIScF3jeaFRpMpE8/lfiTdzf/twXyPBLAGrLRTmkz3AdTnKeh40X8k9L2fdYwEp/42WGXIRGcg==}
+
   html-url-attributes@3.0.1:
     resolution: {integrity: sha512-ol6UPyBWqsrO6EJySPz2O7ZSr856WDrEzM5zMqp+FJJLGMW35cLYmmZnl0vztAZxRUoNZJFTCohfjuIJ8I4QBQ==}
 
@@ -1928,6 +1937,17 @@ packages:
     engines: {node: '>=18'}
     hasBin: true
 
+  i18next-browser-languagedetector@8.2.0:
+    resolution: {integrity: sha512-P+3zEKLnOF0qmiesW383vsLdtQVyKtCNA9cjSoKCppTKPQVfKd2W8hbVo5ZhNJKDqeM7BOcvNoKJOjpHh4Js9g==}
+
+  i18next@24.2.3:
+    resolution: {integrity: sha512-lfbf80OzkocvX7nmZtu7nSTNbrTYR52sLWxPtlXX1zAhVw8WEnFk4puUkCR4B1dNQwbSpEHHHemcZu//7EcB7A==}
+    peerDependencies:
+      typescript: ^5
+    peerDependenciesMeta:
+      typescript:
+        optional: true
+
   iconv-lite@0.6.3:
     resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==}
     engines: {node: '>=0.10.0'}
@@ -2448,6 +2468,22 @@ packages:
     peerDependencies:
       react: ^19.2.3
 
+  react-i18next@15.7.4:
+    resolution: {integrity: sha512-nyU8iKNrI5uDJch0z9+Y5XEr34b0wkyYj3Rp+tfbahxtlswxSCjcUL9H0nqXo9IR3/t5Y5PKIA3fx3MfUyR9Xw==}
+    peerDependencies:
+      i18next: '>= 23.4.0'
+      react: '>= 16.8.0'
+      react-dom: '*'
+      react-native: '*'
+      typescript: ^5
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+      react-native:
+        optional: true
+      typescript:
+        optional: true
+
   react-is@17.0.2:
     resolution: {integrity: sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==}
 
@@ -2862,6 +2898,10 @@ packages:
       jsdom:
         optional: true
 
+  void-elements@3.1.0:
+    resolution: {integrity: sha512-Dhxzh5HZuiHQhbvTW9AMetFfBHDMYpo23Uo9btPXgdYP+3T5S+p+jgNy7spra+veYhBP2dCSgxR/i2Y02h5/6w==}
+    engines: {node: '>=0.10.0'}
+
   w3c-xmlserializer@5.0.0:
     resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==}
     engines: {node: '>=18'}
@@ -3744,7 +3784,7 @@ snapshots:
       react: 19.2.3
       react-dom: 19.2.3(react@19.2.3)
 
-  '@robsun/keystone-web-core@0.1.9(@ant-design/icons@6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@types/react@19.2.7)(antd@6.1.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react-dom@19.2.3(react@19.2.3))(react-router-dom@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react@19.2.3)(use-sync-external-store@1.6.0(react@19.2.3))(vite@7.3.0(@types/node@24.10.4)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2))':
+  '@robsun/keystone-web-core@0.3.0(@ant-design/icons@6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(@types/react@19.2.7)(antd@6.1.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react-dom@19.2.3(react@19.2.3))(react-router-dom@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(react@19.2.3)(typescript@5.9.3)(use-sync-external-store@1.6.0(react@19.2.3))(vite@7.3.0(@types/node@24.10.4)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2))':
     dependencies:
       '@ant-design/icons': 6.1.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       '@vitejs/plugin-react': 5.1.2(vite@7.3.0(@types/node@24.10.4)(jiti@2.6.1)(lightningcss@1.30.2)(yaml@2.8.2))
@@ -3754,8 +3794,11 @@ snapshots:
       dayjs: 1.11.19
       fuse.js: 7.1.0
       gray-matter: 4.0.3
+      i18next: 24.2.3(typescript@5.9.3)
+      i18next-browser-languagedetector: 8.2.0
       react: 19.2.3
       react-dom: 19.2.3(react@19.2.3)
+      react-i18next: 15.7.4(i18next@24.2.3(typescript@5.9.3))(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(typescript@5.9.3)
       react-markdown: 10.1.0(@types/react@19.2.7)(react@19.2.3)
       react-router-dom: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       remark-gfm: 4.0.1
@@ -3764,7 +3807,9 @@ snapshots:
       - '@types/react'
       - debug
       - immer
+      - react-native
       - supports-color
+      - typescript
       - use-sync-external-store
       - vite
 
@@ -4830,6 +4875,10 @@ snapshots:
     dependencies:
       whatwg-encoding: 3.1.1
 
+  html-parse-stringify@3.0.1:
+    dependencies:
+      void-elements: 3.1.0
+
   html-url-attributes@3.0.1: {}
 
   http-proxy-agent@7.0.2:
@@ -4848,6 +4897,16 @@ snapshots:
 
   husky@9.1.7: {}
 
+  i18next-browser-languagedetector@8.2.0:
+    dependencies:
+      '@babel/runtime': 7.28.4
+
+  i18next@24.2.3(typescript@5.9.3):
+    dependencies:
+      '@babel/runtime': 7.28.4
+    optionalDependencies:
+      typescript: 5.9.3
+
   iconv-lite@0.6.3:
     dependencies:
       safer-buffer: 2.1.2
@@ -5537,6 +5596,16 @@ snapshots:
       react: 19.2.3
       scheduler: 0.27.0
 
+  react-i18next@15.7.4(i18next@24.2.3(typescript@5.9.3))(react-dom@19.2.3(react@19.2.3))(react@19.2.3)(typescript@5.9.3):
+    dependencies:
+      '@babel/runtime': 7.28.4
+      html-parse-stringify: 3.0.1
+      i18next: 24.2.3(typescript@5.9.3)
+      react: 19.2.3
+    optionalDependencies:
+      react-dom: 19.2.3(react@19.2.3)
+      typescript: 5.9.3
+
   react-is@17.0.2: {}
 
   react-is@18.3.1: {}
@@ -5961,6 +6030,8 @@ snapshots:
       - supports-color
       - terser
 
+  void-elements@3.1.0: {}
+
   w3c-xmlserializer@5.0.0:
     dependencies:
       xml-name-validator: 5.0.0

package/template/scripts/build.bat

@@ -53,7 +53,7 @@ for /d %%i in ("%EMBED_DIR%\*") do rd /s /q "%%i" 2>nul
 echo [OK] Embed directory cleaned
 
 echo ----------------------------------------
-echo [2/4] Building Frontend
+echo [2/5] Building Frontend
 echo ----------------------------------------
 cd /d "%FRONTEND_DIR%"
 call pnpm build
@@ -67,7 +67,19 @@ echo [OK] Frontend build completed
 cd /d "%PROJECT_ROOT%"
 
 echo ----------------------------------------
-echo [3/4] Building Backend (with embedded frontend)
+echo [3/5] Precompressing Frontend Assets
+echo ----------------------------------------
+call node "%PROJECT_ROOT%\scripts\compress-assets.js"
+if errorlevel 1 (
+    echo [FAIL] Precompression failed
+    set FAILED=1
+    cd /d "%PROJECT_ROOT%"
+    exit /b 1
+)
+echo [OK] Frontend assets precompressed
+
+echo ----------------------------------------
+echo [4/5] Building Backend (with embedded frontend)
 echo ----------------------------------------
 cd /d "%BACKEND_DIR%"
 
@@ -100,7 +112,7 @@ echo [OK] Linux build completed
 cd /d "%PROJECT_ROOT%"
 
 echo ----------------------------------------
-echo [4/4] Copying configuration template
+echo [5/5] Copying configuration template
 echo ----------------------------------------
 if exist "%BACKEND_DIR%\config.example.yaml" (
     copy /Y "%BACKEND_DIR%\config.example.yaml" "%OUTPUT_DIR%\config.example.yaml" >nul

package/template/scripts/build.sh

@@ -52,7 +52,7 @@ find "$EMBED_DIR" -mindepth 1 ! -name '.gitkeep' -delete 2>/dev/null || true
 echo -e "${GREEN}[OK]${NC} Embed directory cleaned"
 
 echo "----------------------------------------"
-echo "[2/4] Building Frontend"
+echo "[2/5] Building Frontend"
 echo "----------------------------------------"
 cd "$FRONTEND_DIR"
 pnpm build
@@ -60,7 +60,13 @@ echo -e "${GREEN}[OK]${NC} Frontend build completed"
 cd "$PROJECT_ROOT"
 
 echo "----------------------------------------"
-echo "[3/4] Building Backend (with embedded frontend)"
+echo "[3/5] Precompressing Frontend Assets"
+echo "----------------------------------------"
+node "$PROJECT_ROOT/scripts/compress-assets.js"
+echo -e "${GREEN}[OK]${NC} Frontend assets precompressed"
+
+echo "----------------------------------------"
+echo "[4/5] Building Backend (with embedded frontend)"
 echo "----------------------------------------"
 cd "$BACKEND_DIR"
 
@@ -75,7 +81,7 @@ echo -e "${GREEN}[OK]${NC} Linux build completed"
 cd "$PROJECT_ROOT"
 
 echo "----------------------------------------"
-echo "[4/4] Copying configuration template"
+echo "[5/5] Copying configuration template"
 echo "----------------------------------------"
 if [ -f "$BACKEND_DIR/config.example.yaml" ]; then
   cp "$BACKEND_DIR/config.example.yaml" "$OUTPUT_DIR/config.example.yaml"