@yuer678/create-kb 0.3.0

package/templates/api/src/types.ts

@@ -0,0 +1,8 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+/** 服务自身的标识信息，由 createApp 注入，健康检查与根路由都会用到 */
+export interface ApiInfo {
+  name: string
+  version: string
+}

package/templates/api/test/app.spec.ts

@@ -0,0 +1,216 @@
+/* eslint-disable */
+// ⚠️ 自动生成文件，请勿直接修改。
+// 源：packages/api/src —— 改动请改源文件后运行 `pnpm sync:api-template`。
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import request from 'supertest'
+import type { Server } from 'node:http'
+import { createApp } from '../src/app'
+import { OPTIONS_TOTAL } from '../src/data/options'
+import { REGION_NODE_COUNT } from '../src/data/regions'
+import { USERS_TOTAL } from '../src/data/users'
+
+let server: Server
+let base: string
+
+beforeAll(async () => {
+  const app = createApp({ name: 'test-api' })
+  await new Promise<void>((resolve) => {
+    server = app.listen(0, () => resolve())
+  })
+  const address = server.address()
+  if (address && typeof address === 'object') {
+    base = `http://127.0.0.1:${address.port}`
+  }
+})
+
+afterAll(() => {
+  server?.close()
+})
+
+describe('健康检查与根路由', () => {
+  it('GET /api/health 返回 ok 与服务标识', async () => {
+    const res = await request(base).get('/api/health')
+    expect(res.status).toBe(200)
+    expect(res.body.status).toBe('ok')
+    expect(res.body.name).toBe('test-api')
+    expect(typeof res.body.uptime).toBe('number')
+  })
+
+  it('GET /health 无前缀同样可用（容器探活）', async () => {
+    const res = await request(base).get('/health')
+    expect(res.status).toBe(200)
+    expect(res.body.status).toBe('ok')
+  })
+
+  it('GET / 列出可用接口', async () => {
+    const res = await request(base).get('/')
+    expect(res.status).toBe(200)
+    expect(res.body.prefix).toBe('/api')
+    expect(res.body.endpoints.length).toBeGreaterThan(0)
+  })
+})
+
+describe('GET /api/users 分页 / 排序 / 搜索', () => {
+  it('默认返回第 1 页 10 条，total 为全量', async () => {
+    const res = await request(base).get('/api/users')
+    expect(res.status).toBe(200)
+    expect(res.body.list).toHaveLength(10)
+    expect(res.body.total).toBe(USERS_TOTAL)
+    expect(res.body.page).toBe(1)
+    expect(res.body.pageSize).toBe(10)
+    expect(res.body.list[0].id).toBe(1)
+  })
+
+  it('翻页返回对应片段且不重叠', async () => {
+    const first = await request(base).get('/api/users?page=1&pageSize=20')
+    const second = await request(base).get('/api/users?page=2&pageSize=20')
+    expect(first.body.list).toHaveLength(20)
+    expect(second.body.list).toHaveLength(20)
+    expect(second.body.list[0].id).toBe(21)
+    const overlap = second.body.list.filter((row: { id: number }) =>
+      first.body.list.some((item: { id: number }) => item.id === row.id),
+    )
+    expect(overlap).toHaveLength(0)
+  })
+
+  it('pageSize 非法时回退默认值，page 越界返回空列表', async () => {
+    const fallback = await request(base).get('/api/users?pageSize=0')
+    expect(fallback.body.pageSize).toBe(10)
+
+    const beyond = await request(base).get('/api/users?page=999')
+    expect(beyond.body.list).toHaveLength(0)
+    expect(beyond.body.total).toBe(USERS_TOTAL)
+  })
+
+  it('keyword 模糊匹配姓名 / 公司 / 邮箱', async () => {
+    const res = await request(base).get('/api/users?keyword=%E6%98%9F%E5%B0%98')
+    // "星尘" 命中星尘科技
+    expect(res.body.total).toBeGreaterThan(0)
+    for (const row of res.body.list) {
+      expect(row.company).toContain('星尘')
+    }
+
+    const byEmail = await request(base).get('/api/users?keyword=user12@')
+    expect(byEmail.body.list[0].email).toBe('user12@example.com')
+  })
+
+  it('sortBy=score&order=desc 正确降序，白名单外字段被忽略', async () => {
+    const desc = await request(base).get('/api/users?sortBy=score&order=desc&pageSize=5')
+    const scores = desc.body.list.map((row: { score: number }) => row.score)
+    expect([...scores].sort((a: number, b: number) => b - a)).toEqual(scores)
+
+    const asc = await request(base).get('/api/users?sortBy=score&order=asc&pageSize=5')
+    const ascScores = asc.body.list.map((row: { score: number }) => row.score)
+    expect([...ascScores].sort((a: number, b: number) => a - b)).toEqual(ascScores)
+
+    // 不在白名单里 → 保持原始顺序
+    const ignored = await request(base).get('/api/users?sortBy=__proto__&order=desc')
+    expect(ignored.body.list[0].id).toBe(1)
+  })
+})
+
+describe('GET /api/regions 树与懒加载', () => {
+  it('GET /api/regions/tree 返回完整嵌套树', async () => {
+    const res = await request(base).get('/api/regions/tree')
+    expect(res.status).toBe(200)
+    expect(res.body.total).toBe(REGION_NODE_COUNT)
+    expect(res.body.list).toHaveLength(8)
+    expect(res.body.list[0].children).toHaveLength(6)
+    expect(res.body.list[0].children[0].children).toHaveLength(8)
+  })
+
+  it('GET /api/regions 不带 parent 返回顶层', async () => {
+    const res = await request(base).get('/api/regions')
+    expect(res.body.parent).toBeNull()
+    expect(res.body.list).toHaveLength(8)
+    expect(res.body.leaf).toBe(false)
+  })
+
+  it('GET /api/regions?parent=a1 只返回下一级且不带 children', async () => {
+    const res = await request(base).get('/api/regions?parent=a1')
+    expect(res.body.list).toHaveLength(6)
+    expect(res.body.parent).toBe('a1')
+    for (const node of res.body.list) {
+      expect(node).not.toHaveProperty('children')
+      expect(node.leaf).toBe(false)
+    }
+  })
+
+  it('末级节点的下一级为空且 leaf 为 true', async () => {
+    const res = await request(base).get('/api/regions?parent=a1-c1-b1')
+    expect(res.body.list).toHaveLength(0)
+    expect(res.body.leaf).toBe(true)
+  })
+
+  it('parent 不存在返回 404', async () => {
+    const res = await request(base).get('/api/regions?parent=not-exist')
+    expect(res.status).toBe(404)
+    expect(res.body.code).toBe(404)
+  })
+})
+
+describe('GET /api/options 搜索与分页', () => {
+  it('默认第 1 页 10 条，total 为全量', async () => {
+    const res = await request(base).get('/api/options')
+    expect(res.body.list).toHaveLength(10)
+    expect(res.body.total).toBe(OPTIONS_TOTAL)
+  })
+
+  it('pageSize 足够大时一次取回全部', async () => {
+    const res = await request(base).get('/api/options?pageSize=500')
+    expect(res.body.list).toHaveLength(OPTIONS_TOTAL)
+  })
+
+  it('keyword 过滤后 total 是过滤后的条数', async () => {
+    const res = await request(base).get('/api/options?keyword=%E5%80%99%E9%80%89%E9%A1%B9%2001')
+    expect(res.body.total).toBeLessThan(OPTIONS_TOTAL)
+    expect(res.body.total).toBeGreaterThan(0)
+  })
+})
+
+describe('写操作、校验与错误处理', () => {
+  it('POST /api/users 参数不合法返回 400 与字段错误', async () => {
+    const res = await request(base).post('/api/users').send({ name: '' })
+    expect(res.status).toBe(400)
+    expect(res.body.code).toBe(400)
+    expect(res.body.errors.name).toBeTruthy()
+  })
+
+  it('POST /api/users 创建成功返回 201', async () => {
+    const res = await request(base).post('/api/users').send({ name: '新用户', score: 88 })
+    expect(res.status).toBe(201)
+    expect(res.body.name).toBe('新用户')
+    expect(res.body.score).toBe(88)
+    expect(res.body.id).toBeGreaterThan(USERS_TOTAL)
+
+    const detail = await request(base).get(`/api/users/${res.body.id}`)
+    expect(detail.status).toBe(200)
+    expect(detail.body.name).toBe('新用户')
+
+    const removed = await request(base).delete(`/api/users/${res.body.id}`)
+    expect(removed.status).toBe(204)
+
+    const again = await request(base).delete(`/api/users/${res.body.id}`)
+    expect(again.status).toBe(404)
+  })
+
+  it('GET /api/users/:id 不存在返回 404 与中文提示', async () => {
+    const res = await request(base).get('/api/users/999999')
+    expect(res.status).toBe(404)
+    expect(res.body.message).toContain('用户不存在')
+  })
+
+  it('未知路由返回 404', async () => {
+    const res = await request(base).get('/api/not-exist')
+    expect(res.status).toBe(404)
+    expect(res.body.code).toBe(404)
+  })
+
+  it('预检请求返回 204 并带 CORS 头', async () => {
+    const res = await request(base)
+      .options('/api/users')
+      .set('Origin', 'http://localhost:5173')
+    expect(res.status).toBe(204)
+    expect(res.headers['access-control-allow-origin']).toBe('http://localhost:5173')
+  })
+})

package/templates/api/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["src", "test"]
+}

package/templates/api/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['test/**/*.spec.ts'],
+  },
+})

package/templates/base/README.md

@@ -0,0 +1,25 @@
+# {{projectName}}
+
+基于 [KB UI](https://github.com/)（@kb/ui）的 Vue 3 + Vite + TypeScript 项目模板。
+
+## 命令
+
+```bash
+pnpm install   # 安装依赖
+pnpm dev       # 启动开发服务器
+pnpm build     # 生产构建
+pnpm preview   # 预览构建产物
+```
+
+## 组件库
+
+全量引入 @kb/ui（`src/main.ts`）：
+
+```ts
+import KbUi from 'kb-ui-vue'
+import '@kb/ui/styles/index.css'
+
+createApp(App).use(KbUi).mount('#app')
+```
+
+暗色主题：给 `<html>` 设置 `data-theme="dark"` 即可。

package/templates/base/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{projectName}}</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/base/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc --noEmit && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "kb-ui-vue": "{{kbVersion}}",
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.0",
+    "typescript": "^5.9.0",
+    "vite": "^8.0.0",
+    "vue-tsc": "^3.0.0"
+  },
+  "overrides": {
+    "js-yaml": "^4.3.2",
+    "fast-uri": "^3.1.0",
+    "electron": "^39.8.10"
+  },
+  "pnpm": {
+    "overrides": {
+      "js-yaml": "^4.1.1",
+      "fast-uri": "^3.1.0"
+    }
+  }
+}

package/templates/base/src/App.vue

@@ -0,0 +1,46 @@
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const dark = ref(false)
+
+function toggleTheme() {
+  dark.value = !dark.value
+  document.documentElement.dataset.theme = dark.value ? 'dark' : 'light'
+}
+</script>
+
+<template>
+  <main class="page">
+    <h1>{{projectName}}</h1>
+    <p class="subtitle">基于 @kb/ui 的 Vue 3 + Vite + TypeScript 项目</p>
+
+    <div class="actions">
+      <KbButton type="primary" @click="toggleTheme">
+        切换到{{ dark ? '亮色' : '暗色' }}主题
+      </KbButton>
+      <KbButton plain>普通按钮</KbButton>
+    </div>
+  </main>
+</template>
+
+<style scoped>
+.page {
+  max-width: 640px;
+  margin: 0 auto;
+  padding: 80px 24px;
+  font-family: var(--kb-font-family);
+  text-align: center;
+}
+
+.subtitle {
+  color: var(--kb-color-text-3);
+  font-size: var(--kb-font-size-sm);
+}
+
+.actions {
+  display: flex;
+  justify-content: center;
+  gap: var(--kb-space-2);
+  margin-top: 32px;
+}
+</style>

package/templates/base/src/main.ts

@@ -0,0 +1,6 @@
+import { createApp } from 'vue'
+import KbUi from 'kb-ui-vue'
+import '@kb/ui/styles/index.css'
+import App from './App.vue'
+
+createApp(App).use(KbUi).mount('#app')

package/templates/base/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "jsx": "preserve",
+    "types": ["vite/client"]
+  },
+  "include": ["src/**/*.ts", "src/**/*.vue", "vite.config.ts"]
+}

package/templates/base/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+})

package/templates/electron/README.md

@@ -0,0 +1,32 @@
+# {{projectName}}
+
+Electron 桌面应用模板（TypeScript + contextIsolation 安全模型）。
+
+## 快速开始
+
+```bash
+pnpm install
+pnpm dev          # 开发模式启动 Electron
+```
+
+## 构建
+
+```bash
+pnpm build        # 打包 Windows 安装包（NSIS + 便携版）→ release/
+pnpm pack         # 仅生成未打包目录（调试用）
+```
+
+## 结构
+
+```
+src/
+├── main/         # 主进程（窗口生命周期、IPC）
+├── preload/      # 白名单 API 桥（contextBridge）
+└── renderer/     # 渲染进程页面
+```
+
+## 安全模型
+
+- `contextIsolation: true` + `nodeIntegration: false`
+- 渲染进程通过 `window.desktop`（preload 暴露的白名单 API）与主进程通信
+- 新增能力：在 `src/main` 注册 `ipcMain.handle`，并在 `src/preload` 对应暴露

package/templates/electron/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "{{packageName}}-desktop",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "main": "dist/main/index.js",
+  "scripts": {
+    "dev": "electron .",
+    "start": "electron .",
+    "typecheck": "tsc --noEmit",
+    "pack": "electron-builder --dir",
+    "build": "electron-builder --win"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "electron": "^39.8.10",
+    "electron-builder": "^26.0.0",
+    "typescript": "^5.9.0"
+  },
+  "build": {
+    "appId": "com.example.{{projectName}}",
+    "productName": "{{projectName}}",
+    "directories": {
+      "output": "release"
+    },
+    "files": [
+      "dist/**/*"
+    ],
+    "win": {
+      "target": [
+        "nsis",
+        "portable"
+      ]
+    },
+    "nsis": {
+      "oneClick": false,
+      "allowToChangeInstallationDirectory": true
+    }
+  },
+  "overrides": {
+    "js-yaml": "^4.3.2",
+    "fast-uri": "^3.1.0",
+    "vite": "^6.3.5",
+    "electron": "^39.8.10"
+  },
+  "pnpm": {
+    "overrides": {
+      "js-yaml": "^4.1.1",
+      "fast-uri": "^3.1.0",
+      "vite": "^6.3.5"
+    }
+  },
+  "dependencies": {}
+}

package/templates/electron/src/main/index.ts

@@ -0,0 +1,36 @@
+import { app, BrowserWindow, ipcMain } from 'electron'
+import { join } from 'node:path'
+
+function createWindow() {
+  const win = new BrowserWindow({
+    width: 960,
+    height: 640,
+    title: '{{projectName}}',
+    webPreferences: {
+      preload: join(import.meta.dirname, '../preload/index.js'),
+      contextIsolation: true,
+      nodeIntegration: false,
+    },
+  })
+
+  // 开发时可加载远程地址，打包后加载本地文件
+  win.loadFile(join(import.meta.dirname, '../renderer/index.html'))
+}
+
+/** 主进程示例 IPC：返回平台信息 */
+ipcMain.handle('app:info', () => ({
+  platform: process.platform,
+  version: app.getVersion(),
+  cwd: process.cwd(),
+}))
+
+app.whenReady().then(() => {
+  createWindow()
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) createWindow()
+  })
+})
+
+app.on('window-all-closed', () => {
+  if (process.platform !== 'darwin') app.quit()
+})

package/templates/electron/src/preload/index.ts

@@ -0,0 +1,10 @@
+import { contextBridge, ipcRenderer } from 'electron'
+
+/** 白名单 API 桥：渲染进程只能通过这里访问主进程能力 */
+const api = {
+  getAppInfo: () => ipcRenderer.invoke('app:info'),
+}
+
+contextBridge.exposeInMainWorld('desktop', api)
+
+export type DesktopApi = typeof api

package/templates/electron/src/renderer/index.html

@@ -0,0 +1,22 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <title>{{projectName}}</title>
+    <style>
+      body { margin: 0; font-family: system-ui, sans-serif; display: grid; place-items: center; height: 100vh; background: #f6f7f9; }
+      .card { padding: 32px 40px; background: #fff; border-radius: 12px; box-shadow: 0 2px 12px rgb(0 0 0 / 8%); text-align: center; }
+      h1 { margin: 0 0 8px; }
+      p { color: #666; }
+      code { background: #eef; padding: 2px 6px; border-radius: 4px; }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <h1>{{projectName}}</h1>
+      <p>Electron 桌面应用模板</p>
+      <p id="info">正在读取主进程信息…</p>
+    </div>
+    <script src="./renderer.js"></script>
+  </body>
+</html>

package/templates/electron/src/renderer/renderer.ts

@@ -0,0 +1,14 @@
+// 渲染进程脚本（通过 preload 暴露的 window.desktop 访问主进程）
+declare global {
+  interface Window {
+    desktop: {
+      getAppInfo(): Promise<{ platform: string; version: string; cwd: string }>
+    }
+  }
+}
+
+window.desktop?.getAppInfo().then((info) => {
+  document.getElementById('info')!.textContent = `平台：${info.platform} · 版本：${info.version}`
+})
+
+export {}

package/templates/electron/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/templates/fullstack/Dockerfile

@@ -0,0 +1,16 @@
+# Web 前端镜像
+FROM node:26-alpine AS web
+WORKDIR /app
+COPY web/package.json ./
+RUN npm install --no-audit --no-fund
+COPY web/ ./
+RUN npm run build
+
+# API 服务镜像
+FROM node:26-alpine AS api
+WORKDIR /app
+COPY server/package.json ./
+RUN npm install --no-audit --no-fund
+COPY server/ ./
+EXPOSE 3000
+CMD ["npm", "start"]

package/templates/fullstack/README.md

@@ -0,0 +1,37 @@
+# {{projectName}}
+
+全栈项目模板：**Vue 3 前端 + Express API + Docker Compose**。
+
+## 目录
+
+```
+├── web/        # Vue 3 + Vite 前端（:5173）
+├── server/     # Express + TypeScript + Zod API（:3000）
+└── docker-compose.yml
+```
+
+## 开发模式
+
+```bash
+pnpm install
+pnpm dev        # 同时启动 web + api（concurrently）
+```
+
+- 前端 http://localhost:5173（/api 已代理到 3000）
+- API 文档见 server/README 或直接访问 /health
+
+## 一键容器化部署
+
+```bash
+pnpm docker:up     # docker compose up -d --build
+pnpm docker:down
+```
+
+- Web http://localhost:8080
+- API http://localhost:3000
+
+## 测试
+
+```bash
+pnpm test          # API 集成测试（vitest + supertest）
+```

package/templates/fullstack/docker-compose.yml

@@ -0,0 +1,26 @@
+version: "3"
+
+services:
+  api:
+    build:
+      context: .
+      target: api
+    ports:
+      - "3000:3000"
+    environment:
+      - PORT=3000
+    healthcheck:
+      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+
+  web:
+    build:
+      context: .
+      target: web
+    ports:
+      - "8080:80"
+    depends_on:
+      api:
+        condition: service_healthy