@robsun/create-keystone-app 0.1.13 → 0.1.15

package/template/apps/web/README.md

@@ -0,0 +1,29 @@
+# Web Shell
+
+## 定位
+- 负责渲染平台 UI，业务模块统一放在 `src/modules/*`。
+- 平台核心能力由 `@robsun/keystone-web-core` 提供。
+
+## 入口
+- `src/main.tsx`：应用入口。
+- `src/app.config.ts`：品牌与模块启用配置。
+- `src/modules/<module>/index.ts`：模块注册入口。
+- `apps/web/.env.example`：前端环境变量模板（Vite 读取）。
+
+## 新建模块
+1) 创建目录：`src/modules/<module>`。
+2) 在 `index.ts` 调用 `registerModule` 注册路由。
+3) 在 `routes.tsx` 配置菜单、权限、帮助文档。
+4) 在 `app.config.ts` 的 `modules.enabled` 启用模块。
+
+## 帮助文档
+- 放在 `src/modules/<module>/help/**`。
+- `helpKey` 与路由 `handle.helpKey` 保持一致。
+
+## 常用命令
+- 开发：`pnpm web:dev`
+- Lint：`pnpm -C apps/web lint`
+- 测试：`pnpm -C apps/web test`
+
+## 嵌入式构建
+- `pnpm build` 会将产物写入 `apps/server/internal/frontend/dist`。

package/template/apps/web/eslint.config.js

@@ -0,0 +1,35 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores([
+    'dist',
+    'build',
+    '*.min.js',
+    'coverage',
+    'node_modules',
+    '.turbo',
+    '.pnpm-store',
+    'apps/server/tmp',
+    'data',
+    '*.log',
+    '.env*',
+  ]),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  },
+])

package/template/apps/web/package.json

@@ -6,28 +6,45 @@
   "scripts": {
     "dev": "vite",
     "build": "vite build",
-    "preview": "vite preview"
+    "build:strict": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\"",
+    "format:check": "prettier --check \"src/**/*.{ts,tsx}\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest"
   },
   "dependencies": {
     "@ant-design/icons": "^6.1.0",
     "@robsun/keystone-web-core": "0.1.7",
     "antd": "^6.0.1",
-    "cookie": "^1.1.1",
     "dayjs": "^1.11.19",
-    "debug": "^4.4.3",
-    "extend": "^3.0.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
-    "react-router": "^7.10.1",
-    "react-router-dom": "^7.10.1",
-    "style-to-js": "^1.1.21"
+    "react-router-dom": "^7.10.1"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@tailwindcss/postcss": "^4.1.17",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.2.0",
+    "@testing-library/user-event": "^14.6.1",
     "@types/node": "^24.10.1",
     "@types/react": "^19.2.5",
     "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "autoprefixer": "^10.4.22",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "jsdom": "^24.1.0",
+    "postcss": "^8.5.6",
+    "tailwindcss": "^4.1.17",
     "typescript": "~5.9.3",
-    "vite": "^7.2.4"
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.4",
+    "vitest": "^2.1.4"
   }
-}
-
+}

package/template/apps/web/postcss.config.js

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+    autoprefixer: {},
+  },
+}

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

@@ -0,0 +1,3 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

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

@@ -4,6 +4,7 @@ import dayjs from 'dayjs'
 import { KeystoneApp, getKeystoneConfig, setKeystoneConfig } from '@robsun/keystone-web-core'
 import { appConfig } from './app.config'
 import '@robsun/keystone-web-core/styles/keystone.css'
+import './index.css'
 import './modules/demo'
 
 setKeystoneConfig(appConfig)

package/template/apps/web/src/modules/demo/help/overview.md

@@ -0,0 +1,12 @@
+---
+helpKey: "demo/tasks"
+title: "Demo Tasks"
+description: "Manage sample tasks in the scaffold."
+category: "demo"
+tags: ["demo", "tasks"]
+---
+
+# Demo Tasks
+
+Use this module as a reference for list + create + update flows. Replace it
+with real business logic when you build new modules.

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

@@ -33,6 +33,8 @@ export const demoRoutes: RouteObject[] = [
     handle: {
       menu: { label: 'Demo Tasks', icon: <AppstoreOutlined /> },
       breadcrumb: 'Demo Tasks',
+      permission: 'demo:task:view',
+      helpKey: 'demo/tasks',
     },
   },
 ].map((route) => ({

package/template/apps/web/tailwind.config.js

@@ -0,0 +1,18 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
+  corePlugins: {
+    preflight: false,
+  },
+  theme: {
+    extend: {
+      colors: {
+        primary: '#1890ff',
+        success: '#52c41a',
+        warning: '#faad14',
+        error: '#ff4d4f',
+      },
+    },
+  },
+  plugins: [],
+}

package/template/apps/web/tests/setup.ts

@@ -0,0 +1,37 @@
+import '@testing-library/jest-dom'
+import { vi } from 'vitest'
+
+window.matchMedia = vi.fn().mockImplementation((query: string) => ({
+  matches: false,
+  media: query,
+  onchange: null,
+  addListener: vi.fn(),
+  removeListener: vi.fn(),
+  addEventListener: vi.fn(),
+  removeEventListener: vi.fn(),
+  dispatchEvent: vi.fn(),
+}))
+
+if (!('ResizeObserver' in window)) {
+  class ResizeObserver {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+  // @ts-expect-error test shim
+  window.ResizeObserver = ResizeObserver
+}
+
+const originalGetComputedStyle = window.getComputedStyle
+window.getComputedStyle = (elt: Element) => {
+  const style = originalGetComputedStyle
+    ? originalGetComputedStyle(elt)
+    : ({} as CSSStyleDeclaration)
+  return {
+    ...style,
+    getPropertyValue: (prop: string) =>
+      style?.getPropertyValue ? style.getPropertyValue(prop) : '',
+  } as CSSStyleDeclaration
+}
+
+export {}

package/template/apps/web/tsconfig.app.json

@@ -5,7 +5,7 @@
     "useDefineForClassFields": true,
     "lib": ["ES2022", "DOM", "DOM.Iterable"],
     "module": "ESNext",
-    "types": ["vite/client"],
+    "types": ["vite/client", "vitest/globals", "@testing-library/jest-dom"],
     "skipLibCheck": true,
     "moduleResolution": "bundler",
     "allowImportingTsExtensions": true,
@@ -19,5 +19,5 @@
     "noFallthroughCasesInSwitch": true,
     "noUncheckedSideEffectImports": true
   },
-  "include": ["src"]
-}
+  "include": ["src", "tests"]
+}

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

@@ -1,6 +1,14 @@
+/// <reference types="vitest" />
 import { createKeystoneViteConfig } from '@robsun/keystone-web-core/vite'
+import path from 'path'
 
 export default createKeystoneViteConfig({
+  helpDir: path.resolve(__dirname, './src/modules'),
+  resolve: {
+    alias: {
+      '@app': path.resolve(__dirname, './src'),
+    },
+  },
   server: {
     port: 3000,
     proxy: {
@@ -10,5 +18,23 @@ export default createKeystoneViteConfig({
       },
     },
   },
-})
-
+  build: {
+    outDir: path.resolve(__dirname, '../server/internal/frontend/dist'),
+    emptyOutDir: false,
+    sourcemap: true,
+    rollupOptions: {
+      output: {
+        manualChunks: {
+          vendor: ['react', 'react-dom'],
+        },
+      },
+    },
+  },
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    setupFiles: './tests/setup.ts',
+    include: ['tests/**/*.{test,spec}.{ts,tsx}'],
+    exclude: ['**/node_modules/**', 'tests/e2e/**'],
+  },
+})

package/template/docker-compose.yml

@@ -0,0 +1,45 @@
+version: '3.8'
+
+services:
+  postgres:
+    image: postgres:17
+    container_name: keystone-postgres
+    restart: unless-stopped
+    ports:
+      - '5432:5432'
+    environment:
+      POSTGRES_DB: keystone
+      POSTGRES_USER: keystone
+      POSTGRES_PASSWORD: keystone
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ['CMD-SHELL', 'pg_isready -U keystone -d keystone']
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  # Redis (optional, uncomment when needed)
+  # redis:
+  #   image: redis:7-alpine
+  #   container_name: keystone-redis
+  #   restart: unless-stopped
+  #   ports:
+  #     - '6379:6379'
+  #   volumes:
+  #     - redisdata:/data
+  #   healthcheck:
+  #     test: ['CMD', 'redis-cli', 'ping']
+  #     interval: 10s
+  #     timeout: 5s
+  #     retries: 5
+
+volumes:
+  pgdata:
+    driver: local
+  # redisdata:
+  #   driver: local
+
+networks:
+  default:
+    name: keystone-network

package/template/docs/CODE_STYLE.md

@@ -0,0 +1,34 @@
+# 编码规范
+
+## 总体原则
+- 依赖自动格式化工具，不做手工对齐。
+- 代码优先可读性，遵循项目约定的目录与命名规则。
+- Web 端使用 ESLint + Prettier；Go 端使用 gofmt。
+
+## TypeScript / React
+- 组件名用 `PascalCase`，hooks 用 `useXxx`。
+- 变量/函数用 `camelCase`，常量用 `UPPER_SNAKE_CASE`。
+- 模块目录固定在 `apps/web/src/modules/<module>`。
+- 路由/菜单/权限统一写在 `routes.tsx` 的 `handle` 元信息里。
+- API 请求集中在 `services/`，类型定义放在 `types.ts`。
+- 使用 Prettier 默认风格（2 空格、单引号、无分号）。
+
+## CSS / UI
+- 全局样式入口：`apps/web/src/index.css`。
+- 组件级样式靠近组件放置，避免跨模块引用。
+
+## Go
+- 文件名用 `snake_case.go`，package 名小写。
+- 统一使用 `gofmt` 格式化代码。
+- 错误处理使用 `fmt.Errorf("...: %w", err)` 包裹。
+- 新模块放在 `apps/server/internal/modules/<module>`，实现 `Module` 接口。
+
+## 常用命令
+```bash
+# Web 端格式化与检查
+pnpm format
+pnpm -C apps/web lint
+
+# Go 端格式化
+gofmt -w apps/server
+```

package/template/docs/CONVENTIONS.md

@@ -1,33 +1,43 @@
-# Keystone App Conventions
-
-## Goals
-- Keep modules predictable across web and server.
-- Keep routing, menus, permissions, and help content in one place.
-- Follow the tradeflow app patterns for structure and naming.
-
-## Project Layout
-- `apps/web/`: React + Vite app.
-- `apps/server/`: Go API app.
-- `apps/web/src/app.config.ts`: web runtime config (modules, branding, approval).
-- `config.yaml`: server runtime config (modules, database, queue, storage).
-
-## Frontend Module Rules
-- Each business module lives in `apps/web/src/modules/<module>`.
-- `index.ts` must register the module:
-  - `registerModule({ name, routes, i18n })`.
-- `routes.tsx` owns menu/breadcrumb/permission metadata via `handle`.
-- Pages go in `pages/`, shared UI in `components/`, API calls in `services/`, types in `types.ts`, shared state in `stores/`.
-- Lazy-load page components and wrap with `Suspense`.
-
-Example module entry:
+# 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 })
 ```
-
-Example route meta:
+- 在 `routes.tsx` 配置菜单/权限/帮助：
 ```tsx
 {
   path: 'orders',
@@ -40,62 +50,15 @@ Example route meta:
   },
 }
 ```
+- 页面放 `pages/`，组件放 `components/`，API 放 `services/`。
 
-## Permissions and Menu Rules
-- Permission format: `domain:resource:action` (wildcards allowed, e.g. `inventory:*:*`).
-- Menus are derived from `handle.menu`. If a route should not appear, omit `handle.menu`.
-- Breadcrumbs are derived from `handle.breadcrumb`.
-- Use `handle.menu.order` to control menu ordering when needed.
-
-## Help Docs
-- Store help markdown under `apps/web/src/modules/<module>/help/**`.
-- Use frontmatter keys: `helpKey`, `title`, `description`, `category`, `tags`, `relatedKeys`.
-- Route `handle.helpKey` must match the markdown `helpKey`.
-- Enable app help by pointing Vite to your help folder (`helpDir` in `vite.config.ts`).
-
-Frontmatter example:
-```md
----
-helpKey: "inventory/warehouses"
-title: "Warehouse Management"
-description: "Manage warehouses and locations."
-category: "inventory"
-tags: ["warehouse", "location"]
-relatedKeys: ["inventory/stock"]
----
-```
-
-## API and Services
-- Use `api` from `@robsun/keystone-web-core` for HTTP.
-- If your API base path changes, call `setApiBaseUrl` once at startup.
-- Keep API calls in `services/*.ts`, return typed data, and let pages handle UI state.
-- For paginated endpoints, map `page`/`page_size` (server) to `page`/`pageSize` (web).
-
-Example service:
-```ts
-import { api, type ApiResponse, type PaginatedData } from '@robsun/keystone-web-core'
-
-export async function listItems(page = 1, pageSize = 20) {
-  const { data } = await api.get<ApiResponse<PaginatedData<Item>>>('/items', {
-    params: { page, page_size: pageSize },
-  })
-  return data.data
-}
-```
-
-## State
-- Use local state for single pages.
-- Use zustand stores for shared state or cross-page flows.
-- Store shape should include `loading`, `error`, `filters`, and a `fetch` method.
-
-## Naming
-- Page components: `*Page.tsx` (e.g. `InventoryListPage.tsx`).
-- API modules: `services/api.ts` or `services/<feature>.ts`.
-- Store modules: `stores/*Store.ts` or `stores/use*Store.ts`.
-- Domain types: `types.ts` (export interfaces and enums).
+## Help 文档
+- 文档放在 `apps/web/src/modules/<module>/help/**`。
+- `helpKey` 与路由 `handle.helpKey` 保持一致。
+- Vite 已配置 `helpDir` 扫描 `src/modules`。
 
-## Backend Module Rules
-For production modules, mirror this layout:
+## 后端模块规范
+推荐结构：
 ```
 apps/server/internal/modules/<module>/
   module.go
@@ -107,7 +70,7 @@ apps/server/internal/modules/<module>/
   bootstrap/seeds/
 ```
 
-Module interface (simplified):
+模块接口：
 ```go
 type Module interface {
     Name() string
@@ -120,15 +83,26 @@ type Module interface {
 }
 ```
 
-Register modules and enable them via `config.yaml` (`modules.enabled`).
-Keep the enabled list aligned with `app.config.ts`.
+## 模块注册与启用
+- 在 `apps/server/internal/modules/manifest.go` 注册模块。
+- 在 `apps/server/config.yaml` 的 `modules.enabled` 启用模块。
+- Web 端 `app.config.ts` 保持同名启用列表。
+
+## 迁移 / 种子 / 权限
+- `startup.InitializeDatabase` 统一执行：核心迁移 + 模块迁移 + 种子 + 权限注册。
+- 模块权限通过 `RegisterPermissions` 注入。
+
+## 任务与队列
+- Worker 在 `cmd/server/main.go` 启动。
+- 模块通过 `RegisterJobs` 注册任务处理器。
+- 队列配置在 `apps/server/config.yaml` 的 `queue` 部分。
 
-## Routing and Responses (Server)
-- Mount API under `/api/v1`.
-- Use auth, rbac, and tenant guards consistently across module routes.
-- Use `github.com/robsuncn/keystone/api/response` helpers for JSON responses.
+## 嵌入式前端
+- Vite `build.outDir` 指向 `apps/server/internal/frontend/dist`。
+- Go 通过 `//go:embed` 嵌入前端产物。
+- 保留 `apps/server/internal/frontend/dist/.gitkeep`，避免 embed 找不到目录。
 
 ## Testing
-- Web: `apps/web/tests/{unit,component,e2e,perf}` with `*.test.ts(x)`.
-- Server: `apps/server/tests/{unit,integration,e2e,fixtures}` with `*_test.go`.
-- Run `go test ./...` for server changes; add a web test runner when needed.
+- Web：`pnpm -C apps/web test`（Vitest）。
+- Server：`go -C apps/server test ./...`。
+- 全量：`pnpm test`。

package/template/package.json

@@ -3,9 +3,21 @@
   "private": true,
   "version": "0.1.0",
   "scripts": {
-    "dev": "pnpm -C apps/web dev",
+    "dev": "node scripts/dev.js",
+    "build": "node scripts/build.js",
+    "build:web": "pnpm --filter web build",
+    "test": "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 ."
+    "server:dev": "go -C apps/server run ./cmd/server",
+    "prepare": "husky"
+  },
+  "devDependencies": {
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4"
   },
   "packageManager": "pnpm@9.15.0"
-}
+}