npm - create-koa-boot - Versions diffs - 1.0.0 - Mend

create-koa-boot 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (935) hide show

package/templates/example/backend/src/app.ts ADDED Viewed

@@ -0,0 +1,75 @@
+import 'reflect-metadata';
+import path from 'path';
+import fs from 'fs';
+import Koa from 'koa';
+import Router from '@koa/router';
+import cors from '@koa/cors';
+import { koaBody } from 'koa-body';
+import serve from 'koa-static';
+import { registerRoutes, middlewares } from 'koa-boot-runtime';
+import config from './config';
+import { RegisterRoutes } from './build/routes';
+import './ai-tools';
+/**
+ * Koa-Boot Example 应用装配：
+ * 中间件（框架 middlewares）+ 系统路由（runtime 预生成）+ 业务路由（项目 tsoa 生成）+ 分端点 API 文档
+ */
+const app = new Koa();
+// 中间件（顺序：错误 → 日志 → CORS → body → 静态 → 认证 → 操作日志 → 权限）
+app.use(middlewares.errorHandler);
+app.use(middlewares.requestLogger);
+app.use(cors());
+app.use(koaBody({ multipart: true }));
+app.use(serve(path.join(__dirname, 'build')));
+app.use(middlewares.authMiddleware);
+// [已禁用] 后端权限检查中间件 — 如需重新启用，取消下面注释
+// app.use(middlewares.permissionMiddleware);
+app.use(middlewares.operationLogger);
+// 系统路由（runtime 包内预生成）+ 系统文档（/api-docs/system）
+registerRoutes(app);
+// 用户业务路由（项目内 tsoa 生成）
+const router = new Router();
+RegisterRoutes(router);
+app.use(router.routes()).use(router.allowedMethods());
+// 业务 API 文档（分端点挂载：/api-docs/business，与系统文档 /api-docs/system 分离）
+const docsRouter = new Router();
+docsRouter.get('/api-docs/business/swagger.json', async (ctx) => {
+  const specPath = path.join(__dirname, 'build', 'swagger.json');
+  try {
+    ctx.type = 'application/json';
+    ctx.body = fs.readFileSync(specPath, 'utf8');
+  } catch {
+    ctx.status = 404;
+    ctx.body = { code: 404, message: 'business swagger.json not found' };
+  }
+});
+docsRouter.get('/api-docs/business', async (ctx) => {
+  const scalarConfig = JSON.stringify({
+    theme: config.scalar.theme,
+    layout: config.scalar.layout,
+    darkMode: config.scalar.darkMode,
+    localization: {
+      locale: config.scalar.localization.locale,
+    },
+  });
+  ctx.body = `<!DOCTYPE html>
+<html>
+<head>
+  <title>Koa-Boot Business API Docs</title>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+</head>
+<body>
+  <script id="api-reference" data-url="/api-docs/business/swagger.json" data-configuration='${scalarConfig}'></script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>`;
+});
+app.use(docsRouter.routes());
+export default app;

package/templates/example/backend/src/business/ai/ai.controller.ts ADDED Viewed

@@ -0,0 +1,38 @@
+// AI 智能助手接口（V7.0）：对话 + Function Calling 工具查询
+import { Body, Controller, Post, Request, Route, Tags } from 'tsoa';
+import { ApiResponse, BizCode, fail, success } from '../../common';
+import { AiChatRequestDto, AiChatResultDto } from './ai.model';
+import { AiService } from './ai.service';
+@Route('ai')
+@Tags('AI 智能助手')
+export class AiController extends Controller {
+  private aiService = new AiService();
+  /**
+   * AI 对话（支持 Function Calling 工具查询业务数据）
+   */
+  @Post('chat')
+  public async chat(
+    @Body() body: AiChatRequestDto,
+    @Request() req: any,
+  ): Promise<ApiResponse<AiChatResultDto>> {
+    const user = req?.state?.user;
+    if (!user?.id) {
+      return fail('未登录或登录已过期', BizCode.UNAUTHORIZED);
+    }
+    if (!body?.messages?.length) {
+      return fail('消息不能为空', BizCode.VALIDATION_ERROR);
+    }
+    try {
+      const result = await this.aiService.chat(
+        body.messages,
+        { userId: user.id, roles: user.roles ?? [] },
+        body.disableTools,
+      );
+      return success(result, '对话成功');
+    } catch (e) {
+      return fail((e as Error).message, BizCode.FAIL);
+    }
+  }
+}

package/templates/example/backend/src/business/ai/ai.model.ts ADDED Viewed

@@ -0,0 +1,37 @@
+/** AI 智能助手模块：对话 DTO 与响应类型定义 */
+/** 对话消息（前端携带历史，role 限定 user/assistant/system） */
+export class AiChatMessageDto {
+  role!: 'user' | 'assistant' | 'system';
+  content!: string;
+  /** 思考模式下的推理内容（前端从上一轮结果中保存，回传时原样带上） */
+  reasoningContent?: string;
+}
+/** 对话请求体 */
+export class AiChatRequestDto {
+  /** 对话消息列表（通常为最近若干条，最新一条为当前问题） */
+  messages!: AiChatMessageDto[];
+  /** 可选：true 时强制关闭工具调用（纯闲聊） */
+  disableTools?: boolean;
+}
+/** 单次工具调用记录（返回给前端展示"回答依据"） */
+export class AiToolCallRecord {
+  /** 工具名 */
+  name!: string;
+  /** 工具入参 */
+  arguments!: Record<string, unknown>;
+  /** 工具返回概要（截断后的数据摘要） */
+  summary!: string;
+}
+/** 对话结果 */
+export class AiChatResultDto {
+  /** 模型最终回复 */
+  reply!: string;
+  /** 本次对话触发的工具调用记录（无则空数组） */
+  toolCalls!: AiToolCallRecord[];
+  /** 思考模式的推理内容（供前端保存，下轮请求原样回传；非思考模式为 null） */
+  reasoningContent?: string | null;
+}

package/templates/example/backend/src/business/ai/ai.service.ts ADDED Viewed

@@ -0,0 +1,137 @@
+// AI 智能助手服务（V7.0）：OpenAI 兼容 Function Calling 对话循环
+// 流程：带工具清单请求模型 → 模型返回"要调哪个工具+参数" → 执行真实查询 →
+//       把结果回填为 tool 消息再请求模型 → 模型基于真实数据生成最终回答
+import {
+  AiMessage,
+  AiToolCall,
+  aiChat,
+  isAiConfigured,
+} from '../../utils/aiClient';
+import { logger } from '../../utils/logger';
+import { AiChatResultDto, AiToolCallRecord } from './ai.model';
+import { aiToolRegistry } from 'koa-boot-runtime';
+/** 系统提示词：限定职责范围，防止幻觉与越权 */
+const SYSTEM_PROMPT = `你是「Koa-Boot 示例平台」的 AI 助手，面向管理员提供数据查询与解读服务。
+你可以通过系统动态下发的工具清单查询真实数据（以实际收到的工具为准）。
+回答规则：
+1. 你是只读查询助手，只能查询数据。任何新增、修改、删除、审核、派单、驳回等写操作请求都【无法执行】，直接礼貌拒绝，并引导用户到平台对应业务模块自行操作，切勿假装完成或编造执行结果。
+2. 只能使用工具查询数据，严禁臆造数字；工具返回为空时如实说明"未查询到相关数据"。
+3. 所有结论必须基于工具返回的真实数据组织，金额默认单位"元"。
+4. 回答简洁、结构化，多用要点和数字；不要罗列原始 JSON。
+5. 用户询问工具清单之外的业务数据时，如实说明当前不支持查询该类数据，并引导用户换个能查的问题。
+6. 如果用户的问题与系统业务数据完全无关（闲聊、写代码、写作等），礼貌说明你的职责范围并引导回业务问题，不回答无关内容。
+7. 涉及查询条件不明确时，可先按合理默认（如最近 30 天）查询，并在回答中注明。`;
+/** 工具调用最多轮数（防死循环） */
+const MAX_TOOL_ROUNDS = 4;
+/** 对话历史裁剪：最多保留最近 20 条消息（防止上下文膨胀、费用飙升） */
+function trimHistory(messages: AiMessage[]): AiMessage[] {
+  if (messages.length <= 20) return messages;
+  return messages.slice(messages.length - 20);
+}
+export class AiService {
+  /**
+   * AI 对话（含工具调用）。
+   * @param messages 前端传来的对话消息（最新一条为用户问题）
+   * @param ctx 登录用户上下文（用于数据权限收口）
+   */
+  async chat(messages: AiChatRequestMessage[], ctx: aiToolRegistry.AiToolContext, disableTools = false): Promise<AiChatResultDto> {
+    const check = isAiConfigured();
+    if (!check.ok) throw new Error(check.reason);
+    const history: AiMessage[] = trimHistory([
+      { role: 'system', content: SYSTEM_PROMPT },
+      ...messages.map((m) => ({
+        role: m.role as AiMessage['role'],
+        content: m.content,
+        // 历史中 assistant 消息携带上一轮的推理内容，原样回传（thinking 模式协议要求）
+        reasoning_content: m.role === 'assistant' ? m.reasoningContent : undefined,
+      })),
+    ]);
+    const toolCalls: AiToolCallRecord[] = [];
+    const toolDefs = aiToolRegistry.listToolDefs();
+    const useTools = !disableTools && toolDefs.length > 0;
+    for (let round = 0; round < MAX_TOOL_ROUNDS; round++) {
+      const res = await aiChat({ messages: history, tools: useTools ? toolDefs : undefined });
+      // 模型决定不再调工具 → 即为最终回答（思考模式下 reasoningContent 一并下发，供前端下轮回传）
+      if (!res.toolCalls.length) {
+        return {
+          reply: res.content ?? '（模型未返回内容，请换个问法）',
+          toolCalls,
+          reasoningContent: res.reasoningContent ?? null,
+        };
+      }
+      // 执行模型指定的工具，收集结果回填
+      const toolMessages: AiMessage[] = [];
+      for (const call of res.toolCalls) {
+        const record = await this.runToolCall(call, ctx);
+        toolCalls.push(record.toolCall);
+        toolMessages.push({
+          role: 'tool',
+          tool_call_id: call.id,
+          content: record.content,
+        });
+      }
+      // assistant 的 tool_calls 与 reasoning_content 必须原样回传（OpenAI 协议 + 思考模式要求）
+      // reasoning_content 仅在模型处于思考模式时存在，未开启时用 undefined 避免污染请求体
+      history.push({
+        role: 'assistant',
+        content: null,
+        tool_calls: res.toolCalls,
+        reasoning_content: res.reasoningContent ?? undefined,
+      });
+      history.push(...toolMessages);
+    }
+    // 轮数耗尽兜底：再问一次不带工具，避免无限循环
+    logger.warn('[ai] 工具调用达到上限，强制收尾');
+    const final = await aiChat({ messages: history });
+    return {
+      reply: final.content ?? '（工具调用过于频繁，请换个问法重试）',
+      toolCalls,
+      reasoningContent: final.reasoningContent ?? null,
+    };
+  }
+  /** 执行单个工具调用：解析参数 → 从注册表执行 → 生成摘要与回填内容 */
+  private async runToolCall(call: AiToolCall, ctx: aiToolRegistry.AiToolContext) {
+    let args: Record<string, any> = {};
+    try {
+      args = JSON.parse(call.function.arguments || '{}');
+    } catch {
+      args = {};
+    }
+    const tool = aiToolRegistry.getAiTool(call.function.name);
+    const result = tool
+      ? await tool.execute(args, ctx)
+      : { error: `未知工具: ${call.function.name}` };
+    const content = JSON.stringify(result);
+    return {
+      toolCall: {
+        name: call.function.name,
+        arguments: args,
+        // 摘要：仅保留前 1500 字符，避免前端展示与日志过大
+        summary: content.length > 1500 ? `${content.slice(0, 1500)}…（已截断）` : content,
+      } as AiToolCallRecord,
+      content,
+    };
+  }
+}
+/** 前端传入的对话消息（宽松结构，从 DTO 转换） */
+export interface AiChatRequestMessage {
+  role: string;
+  content: string;
+  /** 思考模式推理内容（前端保存自上一轮结果，需原样回传） */
+  reasoningContent?: string;
+}

package/templates/example/backend/src/business/demo/demo.controller.ts ADDED Viewed

@@ -0,0 +1,63 @@
+import { Controller, Get, Post, Put, Delete, Path, Query, Body, Route } from 'tsoa';
+import { DemoService } from './demo.service';
+import { CreateDemoDto, UpdateDemoDto } from './demo.model';
+import { PageResult, ApiResponse, pageSuccess, success, fail, BizCode } from '../../common/types';
+@Route('demos')
+export class DemoController extends Controller {
+  private demoService = new DemoService();
+  @Get()
+  public async getAllDemos(@Query() keyword?: string): Promise<ApiResponse<any[]>> {
+    let demos: any[];
+    if (keyword) {
+      demos = await this.demoService.searchDemos(keyword);
+    } else {
+      demos = await this.demoService.getAllDemos();
+    }
+    return success(demos);
+  }
+  @Get('page')
+  public async getAllDemosByPage(
+    @Query() page?: number,
+    @Query() pageSize?: number,
+    @Query() keyword?: string,
+  ): Promise<ApiResponse<{ list: any[]; pagination: PageResult<any>['pagination'] }>> {
+    const result = await this.demoService.getAllDemosByPage({ page, pageSize, keyword });
+    return pageSuccess(result.list, result.pagination);
+  }
+  @Get('{id}')
+  public async getDemoById(@Path() id: string): Promise<ApiResponse<any>> {
+    const demo = await this.demoService.getDemoById(id);
+    if (!demo) {
+      return fail('记录不存在', BizCode.NOT_FOUND, null);
+    }
+    return success(demo);
+  }
+  @Post()
+  public async createDemo(@Body() body: CreateDemoDto): Promise<ApiResponse<any>> {
+    const demo = await this.demoService.createDemo(body);
+    return success(demo, '创建成功');
+  }
+  @Put('{id}')
+  public async updateDemo(@Path() id: string, @Body() body: UpdateDemoDto): Promise<ApiResponse<any>> {
+    const demo = await this.demoService.updateDemo(id, body);
+    if (!demo) {
+      return fail('记录不存在', BizCode.NOT_FOUND, null);
+    }
+    return success(demo, '更新成功');
+  }
+  @Delete('{id}')
+  public async deleteDemo(@Path() id: string): Promise<ApiResponse<boolean>> {
+    const result = await this.demoService.deleteDemo(id);
+    if (!result) {
+      return fail('记录不存在', BizCode.NOT_FOUND, false);
+    }
+    return success(true, '删除成功');
+  }
+}

package/templates/example/backend/src/business/demo/demo.model.ts ADDED Viewed

@@ -0,0 +1,93 @@
+import {
+  IsString,
+  IsNotEmpty,
+  IsOptional,
+  IsNumber,
+  IsEmail,
+  Min,
+  Max,
+  MaxLength,
+} from 'class-validator';
+import { IsPhone } from '../../common/decorators';
+export class Demo {
+  @IsString()
+  id!: string;
+  @IsString()
+  @IsNotEmpty({ message: '姓名不能为空' })
+  @MaxLength(100, { message: '姓名最多100个字符' })
+  name!: string;
+  @IsNumber()
+  @Min(0, { message: '年龄不能为负数' })
+  @Max(150, { message: '年龄超出合理范围' })
+  age!: number;
+  @IsOptional()
+  @IsEmail({}, { message: '邮箱格式不正确' })
+  email!: string | null;
+  @IsOptional()
+  @IsPhone({ message: '请输入有效的手机号码' })
+  phone!: string | null;
+  @IsOptional()
+  @IsString()
+  @MaxLength(1000, { message: '备注最多1000个字符' })
+  notes!: string | null;
+  createdAt!: Date;
+  updatedAt!: Date;
+}
+export class CreateDemoDto {
+  @IsString()
+  @IsNotEmpty({ message: '姓名不能为空' })
+  @MaxLength(100, { message: '姓名最多100个字符' })
+  name!: string;
+  @IsNumber()
+  @Min(0, { message: '年龄不能为负数' })
+  @Max(150, { message: '年龄超出合理范围' })
+  age!: number;
+  @IsOptional()
+  @IsEmail({}, { message: '邮箱格式不正确' })
+  email?: string | null;
+  @IsOptional()
+  @IsPhone({ message: '请输入有效的手机号码' })
+  phone?: string | null;
+  @IsOptional()
+  @IsString()
+  @MaxLength(1000, { message: '备注最多1000个字符' })
+  notes?: string;
+}
+export class UpdateDemoDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(100, { message: '姓名最多100个字符' })
+  name?: string;
+  @IsOptional()
+  @IsNumber()
+  @Min(0, { message: '年龄不能为负数' })
+  @Max(150, { message: '年龄超出合理范围' })
+  age?: number;
+  @IsOptional()
+  @IsEmail({}, { message: '邮箱格式不正确' })
+  email?: string | null;
+  @IsOptional()
+  @IsPhone({ message: '请输入有效的手机号码' })
+  phone?: string | null;
+  @IsOptional()
+  @IsString()
+  @MaxLength(1000, { message: '备注最多1000个字符' })
+  notes?: string;
+}

package/templates/example/backend/src/business/demo/demo.service.ts ADDED Viewed

@@ -0,0 +1,54 @@
+import 'reflect-metadata';
+import { Service } from 'typedi';
+import { prisma } from '../../config/database';
+import { CreateDemoDto, UpdateDemoDto, Demo } from './demo.model';
+import { PageResult, paginateQuery } from '../../common';
+@Service()
+export class DemoService {
+  async getAllDemos(): Promise<Demo[]> {
+    return prisma.demo.findMany({ orderBy: { createdAt: 'desc' } }) as unknown as Demo[];
+  }
+  async getDemoById(id: string): Promise<Demo | null> {
+    return prisma.demo.findUnique({ where: { id } }) as unknown as Demo;
+  }
+  async createDemo(dto: CreateDemoDto): Promise<Demo> {
+    return prisma.demo.create({ data: dto as any }) as unknown as Demo;
+  }
+  async updateDemo(id: string, dto: UpdateDemoDto): Promise<Demo | null> {
+    return prisma.demo.update({ where: { id }, data: dto as any }) as unknown as Demo;
+  }
+  async deleteDemo(id: string): Promise<boolean> {
+    const result = await prisma.demo.delete({ where: { id } });
+    return !!result;
+  }
+  async searchDemos(keyword: string): Promise<Demo[]> {
+    return prisma.demo.findMany({
+      where: {
+        OR: [
+          { name: { contains: keyword } },
+          { email: { contains: keyword } },
+          { phone: { contains: keyword } }
+        ]
+      },
+      orderBy: { createdAt: 'desc' }
+    }) as unknown as Demo[];
+  }
+  async getAllDemosByPage(params?: { page?: number; pageSize?: number; keyword?: string }): Promise<PageResult<Demo>> {
+    const where = params?.keyword ? {
+      OR: [
+        { name: { contains: params.keyword } },
+        { email: { contains: params.keyword } },
+        { phone: { contains: params.keyword } }
+      ]
+    } : {};
+    return paginateQuery<Demo>(prisma.demo, { where, orderBy: { createdAt: 'desc' } }, params);
+  }
+}