create-koa-boot 1.0.0

package/templates/example/AGENTS.md

@@ -0,0 +1,60 @@
+# 项目 AI 开发规则（AGENTS.md）
+
+本文件指导 AI 在此 koa-boot 项目内生成/修改代码。**严格遵守，违反即返工。**
+
+## 技术栈
+
+- 后端：Node 18+ / TypeScript / Koa / tsoa（装饰器路由）/ Prisma / class-validator / typedi
+- 前端：Vue 3 / Element Plus / Vite / Pinia / axios
+- 数据库：MySQL 8（Prisma ORM，表名蛇形）
+
+## 目录约定
+
+```
+backend/
+├── prisma/schema.prisma        # 唯一数据模型源（系统表 + 业务表）
+├── src/app.ts                  # 入口（registerRoutes 注册 tsoa 路由）
+├── src/business/<module>/      # 业务模块（*.model.ts / *.service.ts / *.controller.ts）
+├── src/init/menu-seed.ts       # 菜单/权限种子（新增页面需在此注册）
+└── src/build/                  # tsoa 生成产物（swagger.json / routes.ts，勿手改）
+frontend/
+└── src/api/business/<m>.ts     # 业务 API 封装
+└── src/views/business/<m>/     # 业务页面（index.vue）
+```
+
+## 后端代码规范
+
+1. **分层**：model（class-validator DTO）→ service（typedi + Prisma）→ controller（tsoa 装饰器）。禁止在 controller 写业务逻辑。
+2. **controller**：`@Route('<kebab>s')`，方法返回 `ApiResponse<T>`，用 `success()` / `pageSuccess()` / `fail()` 包装；`BizCode.NOT_FOUND` 用于不存在。
+3. **service**：构造器/方法内使用 `prisma.<model>`（客户端为全局单例）；分页用 `paginateQuery`；入参先过 `normalizeDto`（空串/null → undefined）。
+4. **model**：实体类含 `id!/createdAt/updatedAt`；Create 用必填校验（`@IsNotEmpty({ message: 'xx不能为空' })`），Update 全部 `@IsOptional()`。
+5. **权限**：基于 DB 表 `sys_permissions(path, method)` + 角色关联（RBAC），**无装饰器**。新接口默认受保护，需在菜单/权限种子登记。
+6. **字段命名**：TS 用 camelCase，Prisma 内 `@map` 映射蛇形列名；id 统一 `String @id @default(uuid()) @db.Char(36)`。
+7. **系统字段**：`id/createdAt/updatedAt` 由框架管理，业务代码不得修改。
+
+## 前端代码规范
+
+1. API 封装在 `src/api/business/<m>.ts`，统一从 `../service` 导入 axios 实例（baseURL=/api，自动带 token、解包 code!==200、格式化时间字段）。
+2. 页面在 `src/views/business/<m>/index.vue`，`<script setup lang="ts">`，使用 Element Plus 组件 + 图标。
+3. CRUD 页面必须包含：搜索栏（keyword）、分页表格、新增/编辑对话框、删除确认。
+4. 新增页面后需在 `backend/src/init/menu-seed.ts` 加菜单项（含 `component: 'views/business/<m>/index.vue'`）。
+
+## AI 辅助命令
+
+在项目根执行（`npx create-koa-boot`）：
+
+```bash
+create-koa-boot ai:sync                      # 生成 .ai/ 元数据（entities/api/permissions）供 AI 读取
+create-koa-boot ai:model --name <m> --model <M> [--fields "f:t,f2:t?"]
+create-koa-boot ai:api --name <m> --model <M>
+create-koa-boot ai:vue-page --name <m> --model <M>
+```
+
+**推荐工作流**：
+1. 先 `ai:sync` 刷新 `.ai/` 元数据；
+2. AI 依据 `.ai/entities.json` 理解模型，用 `ai:model` / `ai:api` / `ai:vue-page` 生成代码；
+3. 手写复杂业务时，**严格参照 `src/business/demo/` 蓝本**（模型校验、分页、响应包装、异常处理）。
+
+## 修改 schema 后
+
+`pnpm gen:types` 重新生成 Prisma Client → `pnpm db:push`（开发）→ 新增 controller 后 `pnpm doc` 重新生成 tsoa 路由 → 重启服务。

package/templates/example/backend/.env.example

@@ -0,0 +1,81 @@
+# ===========================================
+# Koa-Boot Example 环境变量示例
+# 复制为 .env.development 并按需修改
+# ===========================================
+
+# --- 运行环境 ---
+NODE_ENV=development
+PORT=3003
+
+# --- 数据库（MySQL + Prisma）---
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=root
+DB_PASSWORD=root
+DB_NAME=koa_boot_example
+DATABASE_URL=mysql://root:root@localhost:3306/koa_boot_example
+
+# --- JWT 认证 ---
+JWT_SECRET=koa-boot-jwt-secret-key-change-in-production
+JWT_EXPIRES_IN=7d
+
+# --- Redis（可选）---
+REDIS_URL=redis://localhost:6379
+REDIS_DB=2
+
+# --- Supabase（可选）---
+SUPABASE_URL=https://your-project-ref.supabase.co
+SUPABASE_SERVICE_KEY=your-service-role-key-here
+SUPABASE_ANON_KEY=your-anon-key-here
+
+# --- 权限控制 ---
+# false = 未注册端点默认放行（开发推荐）
+PERMISSION_STRICT_MODE=false
+MENU_BYPASS_ROLE_FILTER=false
+
+# --- 阿里云 OSS（文件上传）---
+OSS_ACCESS_KEY_ID=your-oss-access-key-id
+OSS_ACCESS_KEY_SECRET=your-oss-access-key-secret
+OSS_BUCKET=your-bucket
+OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
+OSS_REGION=oss-cn-hangzhou
+
+# --- 外部通知方式选择 ---
+# sms / email / wecom / 空（仅站内信）
+EXTERNAL_NOTIFY_CHANNEL=sms
+
+# --- 阿里云短信（EXTERNAL_NOTIFY_CHANNEL=sms 时启用）---
+SMS_ACCESS_KEY_ID=your-sms-access-key-id
+SMS_ACCESS_KEY_SECRET=your-sms-access-key-secret
+SMS_SIGN_NAME=
+SMS_TEMPLATE_CODE=
+
+# --- SMTP 邮件（EXTERNAL_NOTIFY_CHANNEL=email 时启用）---
+EMAIL_SMTP_HOST=
+EMAIL_SMTP_PORT=465
+EMAIL_SMTP_SECURE=true
+EMAIL_SMTP_USER=
+EMAIL_SMTP_PASS=
+EMAIL_FROM=
+
+# --- APP 应用推送（独立链路）---
+APP_PUSH_ENABLED=false
+UNI_PUSH_APPID=
+UNI_PUSH_APPKEY=
+UNI_PUSH_MASTER_SECRET=
+
+# --- 企业微信应用消息 ---
+WECOM_ENABLED=false
+WECOM_CORP_ID=ww-your-corp-id
+WECOM_AGENT_ID=1000002
+WECOM_SECRET=your-wecom-secret
+WECOM_AUTO_BIND=false
+WECOM_H5_BASE_URL=http://localhost:8088/
+
+# --- AI 助手（OpenAI 兼容协议）---
+AI_ENABLED=true
+AI_API_KEY=your-ai-api-key
+# DeepSeek / OpenAI / Kimi / 智谱GLM / 通义千问
+AI_BASE_URL=https://api.deepseek.com
+AI_MODEL=deepseek-chat
+# AI_EXTRA_BODY={"thinking":{"type":"enabled"}}

package/templates/example/backend/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "koa-boot-example",
+  "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": "file:./vendor/koa-boot-runtime-1.0.0.tgz",
+    "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/example/backend/prisma/schema.prisma

@@ -0,0 +1,353 @@
+// ============================================================
+// Koa-Boot Example 数据模型
+// 结构：系统表（15 张，来自 koa-boot-runtime/templates/schema.system.prisma）
+//      + 示例业务表（Demo / SysConfig / SysMessage / NotificationSendLog）
+// 用户业务表直接追加在本文件，与系统表共存。
+// ============================================================
+
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "mysql"
+  url      = env("DATABASE_URL")
+}
+
+// ---------- 系统表（来自 runtime 模板） ----------
+
+model User {
+  id           String      @id @default(uuid()) @db.Char(36)
+  username     String      @unique(map: "username") @db.VarChar(50)
+  password     String      @db.VarChar(255)
+  name         String      @db.VarChar(100)
+  phone        String      @unique(map: "phone") @db.VarChar(20)
+  email        String?     @unique(map: "email") @db.VarChar(100)
+  avatar       String?     @db.VarChar(255)
+  departmentId String?     @map("department_id") @db.Char(36)
+  status       String?     @default("active") @db.VarChar(20)
+  wechatUserid String?     @map("wechat_userid") @db.VarChar(50)
+  pushCid      String?     @map("push_cid") @db.VarChar(100)
+  createdAt    DateTime    @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt    DateTime    @updatedAt @map("updated_at") @db.DateTime(0)
+  department   Department? @relation(fields: [departmentId], references: [id])
+  userRoles    UserRole[]  @relation("UserRoleUser")
+
+  @@index([departmentId], map: "idx_sys_users_department")
+  @@map("sys_users")
+}
+
+model Employee {
+  id           String      @id @default(uuid()) @db.Char(36)
+  name         String      @db.VarChar(100)
+  phone        String      @unique(map: "phone") @db.VarChar(20)
+  email        String?     @unique(map: "email") @db.VarChar(100)
+  position     String?     @db.VarChar(50)
+  salary       Decimal?    @db.Decimal(10, 2)
+  hireDate     DateTime    @map("hire_date") @db.DateTime(0)
+  departmentId String?     @map("department_id") @db.Char(36)
+  status       String?     @default("active") @db.VarChar(20)
+  createdAt    DateTime    @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt    DateTime    @updatedAt @map("updated_at") @db.DateTime(0)
+  department   Department? @relation(fields: [departmentId], references: [id])
+
+  @@index([departmentId], map: "idx_employees_department")
+  @@map("employees")
+}
+
+model Role {
+  id              String           @id @default(uuid()) @db.Char(36)
+  code            String           @unique(map: "code") @db.VarChar(50)
+  name            String           @db.VarChar(100)
+  description     String?          @db.VarChar(255)
+  sort            Int              @default(0)
+  status          String?          @default("active") @db.VarChar(20)
+  createdAt       DateTime         @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt       DateTime         @updatedAt @map("updated_at") @db.DateTime(0)
+  userRoles       UserRole[]       @relation("UserRoleRole")
+  rolePermissions RolePermission[] @relation("RolePermissionRole")
+  roleMenus       RoleMenu[]       @relation("RoleMenuRole")
+
+  @@map("sys_roles")
+}
+
+model Permission {
+  id              String           @id @default(uuid()) @db.Char(36)
+  code            String           @unique(map: "code") @db.VarChar(100)
+  name            String           @db.VarChar(100)
+  type            String           @db.VarChar(20)
+  description     String?          @db.VarChar(255)
+  parentId        String?          @map("parent_id") @db.Char(36)
+  path            String?          @db.VarChar(255)
+  method          String?          @db.VarChar(10)
+  sort            Int              @default(0)
+  status          String?          @default("active") @db.VarChar(20)
+  createdAt       DateTime         @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt       DateTime         @updatedAt @map("updated_at") @db.DateTime(0)
+  parent          Permission?      @relation("PermissionTree", fields: [parentId], references: [id])
+  children        Permission[]     @relation("PermissionTree")
+  rolePermissions RolePermission[] @relation("RolePermissionPermission")
+
+  @@index([type], map: "idx_sys_permissions_type")
+  @@index([parentId], map: "idx_sys_permissions_parent")
+  @@map("sys_permissions")
+}
+
+model Menu {
+  id           String     @id @default(uuid()) @db.Char(36)
+  name         String     @db.VarChar(100)
+  code         String     @unique(map: "code") @db.VarChar(100)
+  parentId     String?    @map("parent_id") @db.Char(36)
+  type         String     @default("menu") @db.VarChar(20)
+  path         String?    @db.VarChar(255)
+  component    String?    @db.VarChar(255)
+  icon         String?    @db.VarChar(100)
+  permissionId String?    @map("permission_id") @db.Char(36)
+  sort         Int        @default(0)
+  visible      Boolean    @default(true)
+  status       String?    @default("active") @db.VarChar(20)
+  createdAt    DateTime   @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt    DateTime   @updatedAt @map("updated_at") @db.DateTime(0)
+  parent       Menu?      @relation("MenuTree", fields: [parentId], references: [id])
+  children     Menu[]     @relation("MenuTree")
+  roleMenus    RoleMenu[] @relation("RoleMenuMenu")
+
+  @@index([parentId], map: "idx_sys_menus_parent")
+  @@index([parentId, sort], map: "idx_sys_menus_sort")
+  @@map("sys_menus")
+}
+
+model Department {
+  id        String       @id @default(uuid()) @db.Char(36)
+  name      String       @db.VarChar(100)
+  code      String       @unique(map: "code") @db.VarChar(50)
+  parentId  String?      @map("parent_id") @db.Char(36)
+  leaderId  String?      @map("leader_id") @db.Char(36)
+  phone     String?      @db.VarChar(20)
+  sort      Int          @default(0)
+  status    String?      @default("active") @db.VarChar(20)
+  createdAt DateTime     @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt DateTime     @updatedAt @map("updated_at") @db.DateTime(0)
+  parent    Department?  @relation("DepartmentTree", fields: [parentId], references: [id])
+  children  Department[] @relation("DepartmentTree")
+  users     User[]       @relation
+  employees Employee[]   @relation
+
+  @@index([parentId], map: "idx_sys_departments_parent")
+  @@index([leaderId], map: "idx_sys_departments_leader")
+  @@map("sys_departments")
+}
+
+model DictType {
+  id          String     @id @default(uuid()) @db.Char(36)
+  code        String     @unique(map: "code") @db.VarChar(100)
+  name        String     @db.VarChar(100)
+  description String?    @db.VarChar(255)
+  status      String?    @default("active") @db.VarChar(20)
+  createdAt   DateTime   @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt   DateTime   @updatedAt @map("updated_at") @db.DateTime(0)
+  items       DictItem[]
+
+  @@map("sys_dict_types")
+}
+
+model DictItem {
+  id          String   @id @default(uuid()) @db.Char(36)
+  typeId      String   @map("type_id") @db.Char(36)
+  label       String   @db.VarChar(100)
+  value       String   @db.VarChar(100)
+  cssClass    String?  @map("css_class") @db.VarChar(50)
+  sort        Int      @default(0)
+  status      String?  @default("active") @db.VarChar(20)
+  description String?  @db.VarChar(255)
+  createdAt   DateTime @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt   DateTime @updatedAt @map("updated_at") @db.DateTime(0)
+  dictType    DictType @relation(fields: [typeId], references: [id])
+
+  @@unique([typeId, value], map: "idx_sys_dict_items_type_value")
+  @@index([typeId], map: "idx_sys_dict_items_type")
+  @@map("sys_dict_items")
+}
+
+model OperationLog {
+  id            String   @id @default(uuid()) @db.Char(36)
+  userId        String?  @map("user_id") @db.Char(36)
+  username      String   @db.VarChar(50)
+  module        String   @db.VarChar(50)
+  action        String   @db.VarChar(50)
+  targetType    String?  @map("target_type") @db.VarChar(50)
+  targetId      String?  @map("target_id") @db.Char(36)
+  description   String?  @db.VarChar(500)
+  requestMethod String?  @map("request_method") @db.VarChar(10)
+  requestUrl    String?  @map("request_url") @db.VarChar(255)
+  requestIp     String?  @map("request_ip") @db.VarChar(50)
+  requestBody   String?  @map("request_body") @db.Text
+  responseCode  Int?     @map("response_code")
+  duration      Int?
+  status        String?  @default("success") @db.VarChar(20)
+  errorMsg      String?  @map("error_msg") @db.Text
+  createdAt     DateTime @default(now()) @map("created_at") @db.DateTime(0)
+
+  @@index([userId], map: "idx_sys_op_logs_user")
+  @@index([module], map: "idx_sys_op_logs_module")
+  @@index([action], map: "idx_sys_op_logs_action")
+  @@index([createdAt], map: "idx_sys_op_logs_created")
+  @@map("sys_operation_logs")
+}
+
+model LoginLog {
+  id        String   @id @default(uuid()) @db.Char(36)
+  userId    String?  @map("user_id") @db.Char(36)
+  username  String   @db.VarChar(50)
+  action    String   @db.VarChar(20)
+  ip        String?  @db.VarChar(50)
+  userAgent String?  @map("user_agent") @db.VarChar(500)
+  os        String?  @db.VarChar(100)
+  browser   String?  @db.VarChar(100)
+  status    String?  @default("success") @db.VarChar(20)
+  message   String?  @db.VarChar(255)
+  createdAt DateTime @default(now()) @map("created_at") @db.DateTime(0)
+
+  @@index([userId], map: "idx_sys_login_logs_user")
+  @@index([username], map: "idx_sys_login_logs_username")
+  @@index([createdAt], map: "idx_sys_login_logs_created")
+  @@map("sys_login_logs")
+}
+
+model FileUpload {
+  id          String   @id @default(uuid()) @db.Char(36)
+  fileNo      String   @unique(map: "fileNo") @map("file_no") @db.VarChar(100)
+  name        String   @db.VarChar(255)
+  size        Int      @default(0)
+  type        String   @db.VarChar(50)
+  url         String   @db.VarChar(500)
+  description String?  @db.VarChar(255)
+  status      String?  @default("active") @db.VarChar(20)
+  createdAt   DateTime @default(now()) @map("created_at") @db.DateTime(0)
+  updatedAt   DateTime @updatedAt @map("updated_at") @db.DateTime(0)
+
+  @@index([fileNo], map: "idx_sys_file_uploads_fileno")
+  @@index([type], map: "idx_sys_file_uploads_type")
+  @@index([createdAt], map: "idx_sys_file_uploads_created")
+  @@map("sys_file_uploads")
+}
+
+model UserRole {
+  userId    String   @map("user_id") @db.Char(36)
+  roleId    String   @map("role_id") @db.Char(36)
+  createdAt DateTime @default(now()) @map("created_at") @db.DateTime(0)
+
+  user User @relation("UserRoleUser", fields: [userId], references: [id], onDelete: Cascade)
+  role Role @relation("UserRoleRole", fields: [roleId], references: [id], onDelete: Cascade)
+
+  @@id([userId, roleId])
+  @@unique([userId, roleId], map: "uk_sys_user_roles")
+  @@index([userId], map: "idx_sys_user_roles_user")
+  @@index([roleId], map: "idx_sys_user_roles_role")
+  @@map("sys_user_roles")
+}
+
+model RolePermission {
+  roleId       String   @map("role_id") @db.Char(36)
+  permissionId String   @map("permission_id") @db.Char(36)
+  createdAt    DateTime @default(now()) @map("created_at") @db.DateTime(0)
+
+  role       Role       @relation("RolePermissionRole", fields: [roleId], references: [id], onDelete: Cascade)
+  permission Permission @relation("RolePermissionPermission", fields: [permissionId], references: [id], onDelete: Cascade)
+
+  @@id([roleId, permissionId])
+  @@index([roleId], map: "idx_sys_role_permissions_role")
+  @@index([permissionId], map: "idx_sys_role_permissions_perm")
+  @@map("sys_role_permissions")
+}
+
+model RoleMenu {
+  roleId    String   @map("role_id") @db.Char(36)
+  menuId    String   @map("menu_id") @db.Char(36)
+  createdAt DateTime @default(now()) @map("created_at") @db.DateTime(0)
+
+  role Role @relation("RoleMenuRole", fields: [roleId], references: [id], onDelete: Cascade)
+  menu Menu @relation("RoleMenuMenu", fields: [menuId], references: [id], onDelete: Cascade)
+
+  @@id([roleId, menuId])
+  @@index([roleId], map: "idx_sys_role_menus_role")
+  @@index([menuId], map: "idx_sys_role_menus_menu")
+  @@map("sys_role_menus")
+}
+
+model SysSequence {
+  seqKey       String   @id @map("seq_key") @db.VarChar(50)
+  currentValue Int      @default(0) @map("current_value")
+  updatedAt    DateTime @updatedAt @map("updated_at") @db.DateTime(0)
+
+  @@map("sys_sequences")
+}
+
+// ---------- 示例业务表 ----------
+
+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/example/backend/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/example/backend/scripts/switch-runtime-local.mjs

@@ -0,0 +1,39 @@
+// 本机 Windows junction 拦截 workaround 的依赖切换脚本。
+// 用法：
+//   node scripts/switch-runtime-local.mjs on    # workspace:* -> 本地 tarball（本机验证用）
+//   node scripts/switch-runtime-local.mjs off   # 本地 tarball -> workspace:*（交付形态）
+// 切换后需重新执行 pnpm install。
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgPath = path.join(__dirname, '../package.json');
+
+const action = process.argv[2];
+if (action !== 'on' && action !== 'off') {
+  console.error('用法: node scripts/switch-runtime-local.mjs <on|off>');
+  process.exit(1);
+}
+
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+const depKey = 'koa-boot-runtime';
+const current = pkg.dependencies?.[depKey];
+
+if (action === 'on') {
+  if (current === 'workspace:*') {
+    pkg.dependencies[depKey] = 'file:./vendor/koa-boot-runtime-1.0.0.tgz';
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+    console.log('[switch-runtime-local] 已切换为本地 tarball，请执行: pnpm install');
+  } else {
+    console.log('[switch-runtime-local] 当前已是本地 tarball，无需切换');
+  }
+} else {
+  if (current?.startsWith('file:')) {
+    pkg.dependencies[depKey] = 'workspace:*';
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+    console.log('[switch-runtime-local] 已恢复 workspace:*，请执行: pnpm install');
+  } else {
+    console.log('[switch-runtime-local] 当前已是 workspace:*，无需切换');
+  }
+}

package/templates/example/backend/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 };
+  },
+});