create-koa-boot 1.0.0

package/templates/example/uniapp/utils/index.js

@@ -0,0 +1,304 @@
+/**
+ * 通用工具函数库
+ */
+
+/**
+ * 格式化日期
+ * @param {Date|string|number} date - 日期
+ * @param {string} format - 格式模板，默认 'YYYY-MM-DD'
+ * @returns {string}
+ */
+export function formatDate(date, format = 'YYYY-MM-DD') {
+	const d = new Date(date)
+	if (isNaN(d.getTime())) return ''
+
+	const map = {
+		YYYY: d.getFullYear(),
+		MM: String(d.getMonth() + 1).padStart(2, '0'),
+		DD: String(d.getDate()).padStart(2, '0'),
+		HH: String(d.getHours()).padStart(2, '0'),
+		mm: String(d.getMinutes()).padStart(2, '0'),
+		ss: String(d.getSeconds()).padStart(2, '0')
+	}
+
+	return format.replace(/YYYY|MM|DD|HH|mm|ss/g, match => map[match])
+}
+
+/**
+ * 格式化日期时间（YYYY-MM-DD HH:mm）
+ * @param {Date|string|number} date - 日期
+ * @returns {string}
+ */
+export function formatTime(date) {
+	return formatDate(date, 'YYYY-MM-DD HH:mm')
+}
+
+/**
+ * 防抖
+ * @param {Function} fn - 需要防抖的函数
+ * @param {number} delay - 延迟时间(ms)
+ * @returns {Function}
+ */
+export function debounce(fn, delay = 300) {
+	let timer = null
+	return function (...args) {
+		if (timer) clearTimeout(timer)
+		timer = setTimeout(() => {
+			fn.apply(this, args)
+			timer = null
+		}, delay)
+	}
+}
+
+/**
+ * 节流
+ * @param {Function} fn - 需要节流的函数
+ * @param {number} interval - 间隔时间(ms)
+ * @returns {Function}
+ */
+export function throttle(fn, interval = 300) {
+	let lastTime = 0
+	return function (...args) {
+		const now = Date.now()
+		if (now - lastTime >= interval) {
+			lastTime = now
+			fn.apply(this, args)
+		}
+	}
+}
+
+/**
+ * 深拷贝
+ * @param {*} obj
+ * @returns {*}
+ */
+export function deepClone(obj) {
+	if (obj === null || typeof obj !== 'object') return obj
+	if (obj instanceof Date) return new Date(obj)
+	if (obj instanceof RegExp) return new RegExp(obj)
+
+	const clone = Array.isArray(obj) ? [] : {}
+	for (const key in obj) {
+		if (Object.prototype.hasOwnProperty.call(obj, key)) {
+			clone[key] = deepClone(obj[key])
+		}
+	}
+	return clone
+}
+
+/**
+ * 获取数据类型
+ * @param {*} val
+ * @returns {string}
+ */
+export function getType(val) {
+	return Object.prototype.toString.call(val).slice(8, -1).toLowerCase()
+}
+
+/**
+ * 判断是否为空值 (null / undefined / '' / [] / {})
+ * @param {*} val
+ * @returns {boolean}
+ */
+export function isEmpty(val) {
+	if (val === null || val === undefined || val === '') return true
+	if (Array.isArray(val) && val.length === 0) return true
+	if (getType(val) === 'object' && Object.keys(val).length === 0) return true
+	return false
+}
+
+/**
+ * 手机号脱敏 138****1234
+ * @param {string} phone
+ * @returns {string}
+ */
+export function maskPhone(phone) {
+	if (!phone || phone.length !== 11) return phone || ''
+	return phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2')
+}
+
+/**
+ * 数字格式化（千分位）
+ * @param {number} num
+ * @returns {string}
+ */
+export function formatNumber(num) {
+	if (num === null || num === undefined) return ''
+	return Number(num).toLocaleString('zh-CN')
+}
+
+/**
+ * 金额格式化（保留两位小数）
+ * @param {number} amount
+ * @param {string} prefix - 前缀，如 '¥'
+ * @returns {string}
+ */
+export function formatAmount(amount, prefix = '¥') {
+	if (amount === null || amount === undefined) return ''
+	return prefix + Number(amount).toFixed(2).replace(/\B(?=(\d{3})+(?!\d))/g, ',')
+}
+
+/**
+ * 页面跳转（自动判断 tabBar 页面使用 switchTab）
+ * @param {string} url - 页面路径
+ * @param {Object} params - 跳转参数
+ */
+export function navigateTo(url, params = {}) {
+	const query = Object.keys(params)
+		.map(k => `${k}=${encodeURIComponent(params[k])}`)
+		.join('&')
+	const fullUrl = query ? `${url}?${query}` : url
+
+	uni.navigateTo({ url: fullUrl })
+}
+
+/**
+ * 存储操作封装
+ */
+export const storage = {
+	get(key) {
+		try {
+			const val = uni.getStorageSync(key)
+			return val ? JSON.parse(val) : null
+		} catch {
+			return uni.getStorageSync(key)
+		}
+	},
+	set(key, value) {
+		try {
+			uni.setStorageSync(key, typeof value === 'object' ? JSON.stringify(value) : value)
+		} catch (e) {
+			console.error(`[Storage] set ${key} failed:`, e)
+		}
+	},
+	remove(key) {
+		try {
+			uni.removeStorageSync(key)
+		} catch (e) {
+			console.error(`[Storage] remove ${key} failed:`, e)
+		}
+	},
+	clear() {
+		try {
+			uni.clearStorageSync()
+		} catch (e) {
+			console.error('[Storage] clear failed:', e)
+		}
+	}
+}
+
+/**
+ * 复制文本到剪贴板
+ * @param {string} text - 要复制的文本
+ * @returns {Promise<boolean>}
+ */
+export function copyText(text) {
+	return new Promise(resolve => {
+		uni.setClipboardData({
+			data: text,
+			success: () => {
+				uni.showToast({ title: '已复制', icon: 'success' })
+				resolve(true)
+			},
+			fail: () => resolve(false)
+		})
+	})
+}
+
+/**
+ * 解析 URL 查询参数
+ * @param {string} url - URL 字符串
+ * @returns {Object}
+ */
+export function parseUrlParams(url) {
+	const params = {}
+	const query = url.split('?')[1]
+	if (!query) return params
+
+	query.split('&').forEach(pair => {
+		const [key, val] = pair.split('=')
+		params[decodeURIComponent(key)] = decodeURIComponent(val || '')
+	})
+	return params
+}
+
+/**
+ * 生成唯一 ID
+ * @param {string} prefix - 前缀
+ * @returns {string}
+ */
+export function uuid(prefix = '') {
+	const s = () => Math.floor((1 + Math.random()) * 0x10000).toString(16).substring(1)
+	return prefix + s() + s() + '-' + s() + '-' + s() + '-' + s() + '-' + s() + s() + s()
+}
+
+/**
+ * 权限检查（基于角色列表）
+ * @param {string[]} userRoles - 当前用户角色
+ * @param {string[]} requiredRoles - 需要的角色
+ * @returns {boolean}
+ */
+export function hasPermission(userRoles, requiredRoles) {
+	if (!requiredRoles || requiredRoles.length === 0) return true
+	if (!userRoles || userRoles.length === 0) return false
+	return requiredRoles.some(role => userRoles.includes(role))
+}
+
+/**
+ * 树形数据转换（平铺 → 树）
+ * @param {Array} list - 平铺数据
+ * @param {string} idKey - ID 字段名
+ * @param {string} parentKey - 父 ID 字段名
+ * @param {string} childrenKey - 子节点字段名
+ * @returns {Array}
+ */
+export function listToTree(list, idKey = 'id', parentKey = 'parentId', childrenKey = 'children') {
+	const map = {}
+	const tree = []
+	list.forEach(item => {
+		map[item[idKey]] = { ...item, [childrenKey]: [] }
+	})
+	list.forEach(item => {
+		const node = map[item[idKey]]
+		if (item[parentKey] && map[item[parentKey]]) {
+			map[item[parentKey]][childrenKey].push(node)
+		} else {
+			tree.push(node)
+		}
+	})
+	return tree
+}
+
+/**
+ * 文件大小格式化
+ * @param {number} bytes
+ * @returns {string}
+ */
+export function formatFileSize(bytes) {
+	if (bytes === 0) return '0 B'
+	const units = ['B', 'KB', 'MB', 'GB', 'TB']
+	const k = 1024
+	const i = Math.floor(Math.log(bytes) / Math.log(k))
+	return (bytes / Math.pow(k, i)).toFixed(i > 0 ? 1 : 0) + ' ' + units[i]
+}
+
+export default {
+	formatDate,
+	formatTime,
+	debounce,
+	throttle,
+	deepClone,
+	getType,
+	isEmpty,
+	maskPhone,
+	formatNumber,
+	formatAmount,
+	navigateTo,
+	storage,
+	copyText,
+	parseUrlParams,
+	uuid,
+	hasPermission,
+	listToTree,
+	formatFileSize
+}

package/templates/example/uniapp/utils/markdown.js

@@ -0,0 +1,139 @@
+/**
+ * 轻量 Markdown → HTML 转换器（用于 AI 回复渲染）
+ * 设计原则：
+ * 1. 零依赖（uni-app 小程序环境无 DOM，不能使用 marked + DOMPurify）
+ * 2. 白名单标签 + 文本转义，天然防 XSS（模型输出不会成为可执行脚本）
+ * 3. 覆盖 AI 回复常用语法：表格 / 标题 / 列表 / 代码块 / 粗体 / 斜体 / 行内代码 / 链接
+ */
+
+/** HTML 转义（在转换前对文本整体转义，保证输出纯文本安全） */
+function escapeHtml(s) {
+	return String(s)
+		.replace(/&/g, '&')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+}
+
+/** 行内语法：粗体 / 斜体 / 行内代码 / 链接 */
+function inline(text) {
+	let t = escapeHtml(text)
+	// 行内代码（先处理，避免内部标记被后续规则误伤）
+	t = t.replace(/`([^`]+)`/g, '<code>$1</code>')
+	// 粗体
+	t = t.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+	// 斜体
+	t = t.replace(/\*([^*]+)\*/g, '<em>$1</em>')
+	// 链接 [text](url)
+	t = t.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, '<a href="$2">$1</a>')
+	return t
+}
+
+/** 是否为表格行（以 | 开头和结尾） */
+function isTableRow(line) {
+	return /^\s*\|.*\|\s*$/.test(line)
+}
+
+/** 是否为表格分隔行（|---|---|，含 - ） */
+function isSepRow(line) {
+	return !!line && /\|/.test(line) && /-/.test(line) && /^\s*\|?[\s:|-]+\|?\s*$/.test(line)
+}
+
+/**
+ * Markdown → HTML
+ * @param {string} src AI 回复的 Markdown 原文
+ * @returns {string} 可交给 uv-parse 渲染的 HTML
+ */
+export function markdownToHtml(src = '') {
+	if (!src) return ''
+	const lines = String(src).replace(/\r\n/g, '\n').split('\n')
+	const out = []
+	let i = 0
+
+	while (i < lines.length) {
+		const line = lines[i]
+
+		// 代码块 ``` ... ```
+		if (/^```/.test(line)) {
+			const buf = []
+			i++
+			while (i < lines.length && !/^```/.test(lines[i])) {
+				buf.push(lines[i])
+				i++
+			}
+			i++ // 跳过结尾 ```
+			out.push('<pre><code>' + escapeHtml(buf.join('\n')) + '</code></pre>')
+			continue
+		}
+
+		// 表格块（表头行 + 分隔行 + 数据行）
+		if (isTableRow(line) && isSepRow(lines[i + 1])) {
+			const header = line.split('|').slice(1, -1).map(s => s.trim())
+			const rows = []
+			i += 2
+			while (i < lines.length && isTableRow(lines[i])) {
+				rows.push(lines[i].split('|').slice(1, -1).map(s => s.trim()))
+				i++
+			}
+			out.push(
+				'<table><thead><tr>' +
+					header.map(c => '<th>' + inline(c) + '</th>').join('') +
+					'</tr></thead><tbody>' +
+					rows.map(r => '<tr>' + r.map(c => '<td>' + inline(c) + '</td>').join('') + '</tr>').join('') +
+					'</tbody></table>',
+			)
+			continue
+		}
+
+		// 标题 # ~ ######
+		const h = line.match(/^(#{1,6})\s+(.*)$/)
+		if (h) {
+			out.push('<h' + h[1].length + '>' + inline(h[2]) + '</h' + h[1].length + '>')
+			i++
+			continue
+		}
+
+		// 无序列表 - / *
+		if (/^\s*[-*]\s+/.test(line)) {
+			const items = []
+			while (i < lines.length && /^\s*[-*]\s+/.test(lines[i])) {
+				items.push(inline(lines[i].replace(/^\s*[-*]\s+/, '')))
+				i++
+			}
+			out.push('<ul>' + items.map(x => '<li>' + x + '</li>').join('') + '</ul>')
+			continue
+		}
+
+		// 有序列表 1. / 1、
+		if (/^\s*\d+[.、]\s+/.test(line)) {
+			const items = []
+			while (i < lines.length && /^\s*\d+[.、]\s+/.test(lines[i])) {
+				items.push(inline(lines[i].replace(/^\s*\d+[.、]\s+/, '')))
+				i++
+			}
+			out.push('<ol>' + items.map(x => '<li>' + x + '</li>').join('') + '</ol>')
+			continue
+		}
+
+		// 空行
+		if (!line.trim()) {
+			i++
+			continue
+		}
+
+		// 普通段落（段内换行转 <br>）
+		const para = []
+		while (
+			i < lines.length &&
+			lines[i].trim() &&
+			!/^```/.test(lines[i]) &&
+			!isTableRow(lines[i])
+		) {
+			para.push(lines[i])
+			i++
+		}
+		out.push('<p>' + inline(para.join('<br>')) + '</p>')
+	}
+
+	return out.join('\n')
+}

package/templates/example/uniapp/utils/push.js

@@ -0,0 +1,54 @@
+/**
+ * APP 推送初始化（UniPush 2.0，独立链路）
+ * - 仅 App 端生效（#ifdef APP-PLUS）；H5/小程序无推送能力，自动跳过
+ * - 前端开关 APP_PUSH_ENABLED 与后端 APP_PUSH_ENABLED 独立，二者都开启才会真正推送
+ * - 流程：onLaunch 获取 cid 并缓存到本地 → 登录成功后由 stores/user.js 调 reportPushCid 上报
+ */
+import { APP_PUSH_ENABLED } from '@/config/index'
+
+/** 本地缓存 key：UniPush 设备 cid */
+const PUSH_CID_KEY = 'push_cid'
+
+/** 当前是否 App 端（APP-PLUS 编译条件，仅 App 包存在） */
+function isApp() {
+	let app = false
+	// #ifdef APP-PLUS
+	app = true
+	// #endif
+	return app
+}
+
+/** 读取本地缓存的 cid */
+export function getPushCid() {
+	return uni.getStorageSync(PUSH_CID_KEY) || ''
+}
+
+/**
+ * 初始化推送（App.vue onLaunch 调用）：
+ * 1. uni.getPushClientId 获取设备 cid 并缓存
+ * 2. 监听系统推送消息（App 前台收到通知栏消息时触发）
+ * 开关关闭或非 App 端直接跳过
+ */
+export function initPush() {
+	if (!APP_PUSH_ENABLED) return
+	if (!isApp()) return
+
+	// 1. 获取 cid（UniPush 2.0 必须）
+	uni.getPushClientId({
+		success: (res) => {
+			const cid = res && res.cid
+			if (cid) {
+				uni.setStorageSync(PUSH_CID_KEY, cid)
+				console.log(`[Push] clientId=${cid}`)
+			}
+		},
+		fail: (err) => {
+			console.warn('[Push] getPushClientId failed', err)
+		}
+	})
+
+	// 2. 前台收到通知栏推送（点击进入 App / 前台展示可在此处理）
+	uni.onPushMessage((res) => {
+		console.log('[Push] onPushMessage', res)
+	})
+}

package/templates/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "1.0.0",
+  "private": true,
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "gen:types": "prisma generate",
+    "db:push": "prisma db push",
+    "doc": "tsoa spec-and-routes -c tsoa.json && node scripts/fix-routes-imports.js",
+    "build": "pnpm gen:types && pnpm doc && tsc -p tsconfig.build.json",
+    "type-check": "tsc --noEmit",
+    "clean": "rimraf dist src/build"
+  },
+  "engines": {
+    "node": ">=18.19.0"
+  },
+  "dependencies": {
+    "@koa/cors": "^5.0.0",
+    "@prisma/client": "^5.19.1",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
+    "koa": "^3.1.1",
+    "koa-body": "^8.0.0",
+    "koa-boot-runtime": "^1.0.0",
+    "koa-static": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/koa": "^2.15.0",
+    "@types/koa__cors": "^5.0.0",
+    "@types/koa-static": "^4.0.4",
+    "@types/node": "^25.0.10",
+    "prisma": "^5.19.1",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/templates/prisma/schema.business.prisma

@@ -0,0 +1,72 @@
+// ============================================================
+// 业务表 Schema 片段（示例业务表）
+// CLI 生成项目时，本片段与 koa-boot-runtime 提供的系统表片段合并
+// 为项目的 prisma/schema.prisma。用户业务表继续追加在业务片段即可。
+// ============================================================
+
+model Demo {
+  id        String   @id @default(uuid()) @db.Char(36)
+  name      String   @db.VarChar(100)
+  age       Int
+  email     String?  @db.VarChar(100)
+  phone     String?  @db.VarChar(20)
+  notes     String?  @db.Text
+  createdAt DateTime @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt DateTime @updatedAt @map("updated_at") @db.DateTime(0)
+
+  @@map("demos")
+}
+
+model SysConfig {
+  id          String   @id @default(uuid()) @db.Char(36)
+  configKey   String   @unique(map: "config_key") @map("config_key") @db.VarChar(100)
+  configValue String   @map("config_value") @db.Text
+  description String?  @db.VarChar(255)
+  createdAt   DateTime @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt   DateTime @updatedAt @map("updated_at") @db.DateTime(0)
+
+  @@map("sys_config")
+}
+
+model SysMessage {
+  id               String   @id @default(uuid()) @db.Char(36)
+  msgType          String   @map("msg_type") @db.VarChar(20)
+  title            String   @db.VarChar(200)
+  content          String   @db.Text
+  templateCode     String   @map("template_code") @db.VarChar(50)
+  receiverUserId   String   @map("receiver_user_id") @db.Char(36)
+  receiverRoleCode String?  @map("receiver_role_code") @db.VarChar(50)
+  operatorId       String?  @map("operator_id") @db.Char(36)
+  isRead           Boolean  @default(false) @map("is_read")
+  readTime         DateTime? @map("read_time") @db.DateTime(0)
+  bizType          String   @map("biz_type") @db.VarChar(30)
+  bizId            String?  @map("biz_id") @db.VarChar(50)
+  bizId2           String?  @map("biz_id2") @db.VarChar(50)
+  extraData        Json?    @map("extra_data")
+  createdAt        DateTime @default(now()) @map("created_at") @db.DateTime(0)
+
+  @@index([receiverUserId, isRead, createdAt], map: "idx_sys_messages_receiver_read_created")
+  @@index([bizType, bizId], map: "idx_sys_messages_biz")
+  @@index([templateCode, createdAt], map: "idx_sys_messages_template_created")
+  @@map("sys_messages")
+}
+
+model NotificationSendLog {
+  id              String   @id @default(uuid()) @db.Char(36)
+  channel         String   @map("channel") @db.VarChar(20)
+  templateCode    String   @map("template_code") @db.VarChar(50)
+  title           String   @db.VarChar(200)
+  content         String?  @db.Text
+  receiverUserIds String   @map("receiver_user_ids") @db.Text
+  externalIds     String?  @map("external_ids") @db.Text
+  status          String   @default("pending") @db.VarChar(20)
+  failReason      String?  @map("fail_reason") @db.VarChar(500)
+  retryCount      Int      @default(0) @map("retry_count")
+  bizType         String?  @map("biz_type") @db.VarChar(30)
+  bizId           String?  @map("biz_id") @db.VarChar(50)
+  createdAt       DateTime @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt       DateTime @updatedAt @map("updated_at") @db.DateTime(0)
+
+  @@index([channel, status, createdAt], map: "idx_send_log_channel_status_created")
+  @@map("notification_send_logs")
+}

package/templates/scripts/fix-routes-imports.js

@@ -0,0 +1,23 @@
+'use strict';
+// tsoa 生成的 routes.ts 使用 namespace 导入 KoaRouter，NodeNext/ESM 下需改为类型导入 Router
+const fs = require('fs');
+const path = require('path');
+
+const routesFilePath = path.join(__dirname, '../src/build/routes.ts');
+
+console.log('Fixing routes.ts imports...');
+
+let content = fs.readFileSync(routesFilePath, 'utf8');
+
+content = content.replace(
+  "import type * as KoaRouter from '@koa/router';",
+  "import type { Router } from '@koa/router';"
+);
+
+content = content.replace(
+  'export function RegisterRoutes(router: KoaRouter) {',
+  'export function RegisterRoutes(router: Router) {'
+);
+
+fs.writeFileSync(routesFilePath, content, 'utf8');
+console.log('routes.ts imports fixed successfully!');

package/templates/src/ai-tools.ts

@@ -0,0 +1,32 @@
+// ============================================================
+// AI 工具注册示例（演示 koa-boot-runtime 的 aiToolRegistry 机制）
+// 业务工具在此文件通过 registerAiTool 注册，AI 对话自动下发工具清单。
+// 原则：只注册查询类只读工具；执行函数内部自行收口数据权限。
+// ============================================================
+import { aiToolRegistry } from 'koa-boot-runtime';
+
+aiToolRegistry.registerAiTool({
+  definition: {
+    type: 'function',
+    function: {
+      name: 'query_demo_stats',
+      description: '查询演示数据统计（示例工具：演示 AI 工具注册表用法）',
+      parameters: {
+        type: 'object',
+        properties: {
+          limit: { type: 'number', description: '返回条数，默认 10，最大 50' },
+        },
+      },
+    },
+  },
+  execute: async (args) => {
+    const { prisma } = await import('./config/database.js');
+    const limit = Math.min(Number(args.limit ?? 10), 50);
+    const demos = await prisma.demo.findMany({
+      select: { id: true, name: true, age: true, email: true },
+      take: limit,
+      orderBy: { createdAt: 'desc' },
+    });
+    return { total: demos.length, demos };
+  },
+});