@yuer678/create-kb 0.3.0

package/templates/fullstack/server/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/fullstack/server/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/fullstack/server/vitest.config.ts

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

package/templates/fullstack/web/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>Fullstack</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/fullstack/web/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "web",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --port 5173",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "vue": "^3.5.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^6.0.0",
+    "typescript": "^5.9.0",
+    "vite": "^8.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/fullstack/web/src/App.vue

@@ -0,0 +1,108 @@
+<script setup lang="ts">
+import { onMounted, ref } from 'vue'
+
+const items = ref<{ id: number; name: string; done: boolean }[]>([])
+const name = ref('')
+const error = ref('')
+
+const API = import.meta.env.VITE_API ?? 'http://localhost:3000'
+
+async function load() {
+  try {
+    const res = await fetch(`${API}/items`)
+    items.value = await res.json()
+    error.value = ''
+  } catch {
+    error.value = '无法连接 API（请先启动后端）'
+  }
+}
+
+async function add() {
+  if (!name.value) return
+  await fetch(`${API}/items`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ name: name.value }),
+  })
+  name.value = ''
+  await load()
+}
+
+onMounted(load)
+</script>
+
+<template>
+  <main class="page">
+    <h1>Fullstack 模板</h1>
+    <p class="sub">前端 Vue + 后端 Express，通过 HTTP 通信</p>
+    <p v-if="error" class="error">{{ error }}</p>
+    <form class="row" @submit.prevent="add">
+      <input v-model="name" placeholder="新任务名称" />
+      <button type="submit">添加</button>
+    </form>
+    <ul class="list">
+      <li v-for="item in items" :key="item.id">
+        <span :class="{ done: item.done }">{{ item.name }}</span>
+        <small>#{{ item.id }}</small>
+      </li>
+    </ul>
+  </main>
+</template>
+
+<style>
+* {
+  box-sizing: border-box;
+}
+body {
+  margin: 0;
+  font-family: system-ui, sans-serif;
+  background: #f6f7f9;
+}
+.page {
+  max-width: 560px;
+  margin: 48px auto;
+  padding: 24px;
+  background: #fff;
+  border-radius: 12px;
+  box-shadow: 0 2px 12px rgb(0 0 0 / 8%);
+}
+.sub {
+  color: #888;
+}
+.error {
+  color: #d33;
+  font-size: 14px;
+}
+.row {
+  display: flex;
+  gap: 8px;
+}
+.row input {
+  flex: 1;
+  padding: 8px 12px;
+  border: 1px solid #ddd;
+  border-radius: 8px;
+}
+.row button {
+  padding: 8px 16px;
+  border: none;
+  border-radius: 8px;
+  background: #3b82f6;
+  color: #fff;
+  cursor: pointer;
+}
+.list {
+  padding: 0;
+  list-style: none;
+}
+.list li {
+  display: flex;
+  justify-content: space-between;
+  padding: 10px 0;
+  border-bottom: 1px solid #eee;
+}
+.done {
+  text-decoration: line-through;
+  color: #999;
+}
+</style>

package/templates/fullstack/web/src/main.ts

@@ -0,0 +1,4 @@
+import { createApp } from 'vue'
+import App from './App.vue'
+
+createApp(App).mount('#app')

package/templates/fullstack/web/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "preserve",
+    "skipLibCheck": true,
+    "types": ["vite/client"],
+    "noEmit": true
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/fullstack/web/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3000',
+        changeOrigin: true,
+        rewrite: (p) => p.replace(/^\/api/, ''),
+      },
+    },
+  },
+})

package/templates/react/README.md

@@ -0,0 +1,8 @@
+# {{projectName}}
+
+React 19 + Vite + TypeScript 模板。
+
+```bash
+pnpm install
+pnpm dev
+```

package/templates/react/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="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "{{packageName}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^5.0.0",
+    "typescript": "^5.9.0",
+    "vite": "^8.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/react/src/App.css

@@ -0,0 +1,32 @@
+* {
+  box-sizing: border-box;
+}
+body {
+  margin: 0;
+  font-family: system-ui, sans-serif;
+  background: #f6f7f9;
+}
+.page {
+  max-width: 480px;
+  margin: 64px auto;
+  padding: 32px;
+  background: #fff;
+  border-radius: 12px;
+  box-shadow: 0 2px 12px rgb(0 0 0 / 8%);
+  text-align: center;
+}
+.sub {
+  color: #888;
+}
+.btn {
+  padding: 8px 20px;
+  border: none;
+  border-radius: 8px;
+  background: #3b82f6;
+  color: #fff;
+  font-size: 15px;
+  cursor: pointer;
+}
+.btn:hover {
+  background: #2563eb;
+}

package/templates/react/src/App.tsx

@@ -0,0 +1,16 @@
+import { useState } from 'react'
+import './App.css'
+
+export default function App() {
+  const [count, setCount] = useState(0)
+  const appName = '{{projectName}}'
+  return (
+    <main className="page">
+      <h1>{appName}</h1>
+      <p className="sub">React 19 + Vite + TypeScript 模板</p>
+      <button className="btn" onClick={() => setCount((c) => c + 1)}>
+        点击计数：{count}
+      </button>
+    </main>
+  )
+}

package/templates/react/src/main.tsx

@@ -0,0 +1,9 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)

package/templates/react/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src"]
+}

package/templates/react/vite.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+  },
+})

package/templates/starter/README.md

@@ -0,0 +1,28 @@
+# {{projectName}}
+
+基于 [KB UI](https://github.com/)（@kb/ui）的 Vue 3 + Vite + TypeScript 完整示例模板。
+
+包含：表单联动（Input/Checkbox/Radio/Select）、数据表格（Table + 自定义单元格）、
+消息提示（message）、对话框（Dialog）、暗色主题切换。
+
+## 命令
+
+```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/starter/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/starter/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"
+    }
+  }
+}