create-koa-boot 1.0.0

package/ai/metadata.js

@@ -0,0 +1,107 @@
+'use strict';
+/**
+ * ai:sync —— 生成 AI 辅助元数据
+ *
+ * 从用户项目提取结构化元数据，供 AI 精确理解项目：
+ *  - .ai/entities.json   模型清单（来源：prisma/schema.prisma）
+ *  - .ai/api-list.json   API 端点清单（来源：tsoa 生成的 src/build/swagger.json）
+ *  - .ai/permissions.json 权限/菜单清单（来源：src/init/menu-seed.ts，尽力解析）
+ *
+ * 用法：create-koa-boot ai:sync [--out .ai]
+ */
+const fs = require('fs');
+const path = require('path');
+const { parseSchema } = require('./schema-parser');
+
+/** 从 Prisma 类型推断"业务可写"字段（排除系统字段/自增字段） */
+const SYSTEM_FIELDS = new Set(['id', 'createdAt', 'updatedAt', 'deletedAt']);
+
+function toEntities(schema) {
+  return schema.models.map((m) => ({
+    name: m.name,
+    table: m.tableName,
+    fields: m.fields.map((f) => ({
+      name: f.name,
+      type: f.type,
+      optional: f.optional,
+      isId: f.isId,
+      isUnique: f.isUnique,
+      hasDefault: f.hasDefault,
+      writable: !SYSTEM_FIELDS.has(f.name) && !f.isId && !f.updatedAt,
+    })),
+  }));
+}
+
+/** 从 swagger.json 提取 API 端点清单 */
+function toApiList(swagger) {
+  const paths = swagger.paths || {};
+  const list = [];
+  for (const [p, methods] of Object.entries(paths)) {
+    for (const [method, op] of Object.entries(methods)) {
+      if (!['get', 'post', 'put', 'delete', 'patch'].includes(method)) continue;
+      list.push({
+        method: method.toUpperCase(),
+        path: p,
+        summary: op.summary || op.operationId || '',
+        tags: op.tags || [],
+        security: !!op.security,
+      });
+    }
+  }
+  return list;
+}
+
+/** 从 menu-seed.ts 尽力解析菜单/权限清单（失败返回空数组，不阻塞） */
+function toPermissions(seedSource) {
+  const items = [];
+  const re = /code:\s*'([\w:]+)'[\s\S]*?path:\s*'([^']*)'/g;
+  let m;
+  while ((m = re.exec(seedSource))) {
+    items.push({ code: m[1], path: m[2] });
+  }
+  return items;
+}
+
+function runSync(targetDir, outDir) {
+  const schemaPath = path.join(targetDir, 'prisma', 'schema.prisma');
+  const swaggerPath = path.join(targetDir, 'src', 'build', 'swagger.json');
+  const seedPath = path.join(targetDir, 'src', 'init', 'menu-seed.ts');
+  const errors = [];
+
+  if (!fs.existsSync(schemaPath)) {
+    errors.push(`未找到 ${schemaPath}`);
+  }
+  if (!fs.existsSync(swaggerPath)) {
+    errors.push(`未找到 ${swaggerPath}（请先运行 pnpm doc 或 pnpm build 生成 swagger.json）`);
+  }
+  if (errors.length) {
+    for (const e of errors) console.error('  ✗ ' + e);
+    process.exit(1);
+  }
+
+  fs.mkdirSync(outDir, { recursive: true });
+
+  // 1. entities.json
+  const schema = parseSchema(fs.readFileSync(schemaPath, 'utf8'));
+  const entities = toEntities(schema);
+  fs.writeFileSync(path.join(outDir, 'entities.json'), JSON.stringify(entities, null, 2), 'utf8');
+  console.log(`  ✓ entities.json 已生成（${entities.length} 个模型）`);
+
+  // 2. api-list.json
+  const swagger = JSON.parse(fs.readFileSync(swaggerPath, 'utf8'));
+  const apiList = toApiList(swagger);
+  fs.writeFileSync(path.join(outDir, 'api-list.json'), JSON.stringify(apiList, null, 2), 'utf8');
+  console.log(`  ✓ api-list.json 已生成（${apiList.length} 个端点）`);
+
+  // 3. permissions.json（尽力解析，缺失不报错）
+  let permissions = [];
+  if (fs.existsSync(seedPath)) {
+    permissions = toPermissions(fs.readFileSync(seedPath, 'utf8'));
+  }
+  fs.writeFileSync(path.join(outDir, 'permissions.json'), JSON.stringify(permissions, null, 2), 'utf8');
+  console.log(`  ✓ permissions.json 已生成（${permissions.length} 个权限点）`);
+
+  console.log(`\n  ✅ AI 元数据已写入 ${path.relative(targetDir, outDir)}/，可让 AI 读取后生成代码。`);
+}
+
+module.exports = { runSync };

package/ai/schema-parser.js

@@ -0,0 +1,127 @@
+'use strict';
+/**
+ * Prisma schema 轻量解析器（零依赖）
+ *
+ * 从 prisma/schema.prisma 提取：
+ *  - model 名称、表名（@@map）、字段（名称/类型/可选/主键/默认值/唯一/映射列名）
+ *  - enum 定义
+ *
+ * 输入格式假设遵循本框架约定（id @id @default(uuid())、createdAt/updatedAt 系统字段等），
+ * 不解析复杂关系（@relation 保留原始属性串，供生成器判断是否跳过）。
+ */
+
+/** 按花括号深度切分顶层 block：model / enum / datasource / generator / type */
+function parseBlocks(source) {
+  const lines = source.split('\n');
+  const blocks = [];
+  let current = null;
+  let depth = 0;
+
+  for (const raw of lines) {
+    const line = raw.replace(/\r$/, '');
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('//')) {
+      if (current) current.body.push('');
+      continue;
+    }
+
+    if (!current) {
+      const m = trimmed.match(/^(model|enum|datasource|generator|type)\s+(\w+)\s*\{/);
+      if (m) {
+        current = { kind: m[1], name: m[2], body: [] };
+        depth = 1;
+        continue;
+      }
+      continue; // 顶层杂项（如注释、空行）
+    }
+
+    // 计数花括号（字符串内不处理，schema 中属性串不含裸花括号）
+    depth += (line.match(/{/g) || []).length - (line.match(/}/g) || []).length;
+
+    if (depth > 0) {
+      current.body.push(trimmed);
+    } else {
+      // 收尾行可能同时含属性与 }（少见，忽略属性残留）
+      blocks.push(current);
+      current = null;
+      depth = 0;
+    }
+  }
+  if (current) blocks.push(current);
+  return blocks;
+}
+
+/** 解析 model 内一行字段定义 */
+function parseFieldLine(line) {
+  // 形如: name String? @db.VarChar(100) @map("config_key") @default(now())
+  const m = line.match(/^(\w+)\s+([\w.]+)(\??)\s*(.*)$/);
+  if (!m) return null;
+  const [, name, type, optional, attrsRaw] = m;
+  const attrs = attrsRaw;
+  return {
+    name,
+    type,
+    optional: optional === '?',
+    isId: /@id\b/.test(attrs),
+    isUnique: /@unique\b/.test(attrs),
+    hasDefault: /@default\s*\(/.test(attrs),
+    updatedAt: /@updatedAt\b/.test(attrs),
+    createdAt: /@default\(now\(\)\)/.test(attrs) && type === 'DateTime',
+    map: (attrs.match(/@map\("([^"]+)"\)/) || [])[1] || null,
+    dbType: (attrs.match(/@db\.([\w(]+)/) || [])[1] || null,
+    raw: attrs.trim(),
+  };
+}
+
+/** 解析 @@map 表名 / @@index / @@unique 等块级属性 */
+function parseBlockAttrs(body) {
+  const tableNameMatch = body.find((l) => l.startsWith('@@map('));
+  return {
+    tableName: (tableNameMatch || '').match(/@@map\("([^"]+)"\)/)?.[1] || null,
+    hasCompositeId: body.some((l) => l.startsWith('@@id')),
+  };
+}
+
+/** 解析单个 model */
+function parseModel(body) {
+  const fields = [];
+  for (const line of body) {
+    if (!line || line.startsWith('@') || line.startsWith('@@')) continue;
+    const f = parseFieldLine(line);
+    if (f) fields.push(f);
+  }
+  const { tableName } = parseBlockAttrs(body);
+  return { fields, tableName };
+}
+
+/** 解析 enum */
+function parseEnum(body) {
+  const values = [];
+  for (const line of body) {
+    const m = line && line.match(/^(\w+)(\s+@map\("([^"]+)"\))?/);
+    if (m && !line.startsWith('@@')) values.push(m[1]);
+  }
+  return values;
+}
+
+/**
+ * 解析 schema.prisma 源码
+ * @returns {{ models: Array<{name, tableName, fields}>, enums: Array<{name, values}> }}
+ */
+function parseSchema(source) {
+  const blocks = parseBlocks(source);
+  const models = [];
+  const enums = [];
+
+  for (const block of blocks) {
+    if (block.kind === 'model') {
+      const { fields, tableName } = parseModel(block.body);
+      models.push({ name: block.name, tableName: tableName || block.name.toLowerCase() + 's', fields });
+    } else if (block.kind === 'enum') {
+      enums.push({ name: block.name, values: parseEnum(block.body) });
+    }
+  }
+  return { models, enums };
+}
+
+module.exports = { parseSchema, parseBlocks, parseModel, parseEnum };

package/ai.js

@@ -0,0 +1,95 @@
+'use strict';
+/**
+ * AI 辅助命令入口（在已有 koa-boot 项目内运行）
+ *
+ * 用法（在项目根目录执行，npx create-koa-boot ai:*）：
+ *   create-koa-boot ai:sync                       # 生成 .ai/ 元数据（entities/api/permissions）
+ *   create-koa-boot ai:model --name demo --model Demo --fields "name:string,age:int"
+ *                                                 # 生成业务模型 + DTO（src/business/<name>/<name>.model.ts）
+ *   create-koa-boot ai:api --name demo --model Demo
+ *                                                 # 生成 controller + service
+ *   create-koa-boot ai:vue-page --name demo --model Demo
+ *                                                 # 生成前端 API + CRUD 页面
+ */
+const path = require('path');
+const { runSync } = require('./ai/metadata');
+const { generateModel, generateApi, generateVuePage } = require('./ai/generators');
+
+function usage() {
+  console.log('用法: create-koa-boot ai:<sync|model|api|vue-page> [options]');
+  console.log('  ai:sync                        生成 .ai/ 元数据（entities.json / api-list.json / permissions.json）');
+  console.log('  ai:model  --name <m> [--model <M>] [--fields "f:t,f2:t?"]');
+  console.log('                                  生成模型 + DTO（--fields 可选，默认读取 schema.prisma 指定模型）');
+  console.log('  ai:api    --name <m> --model <M>   生成 controller + service');
+  console.log('  ai:vue-page --name <m> --model <M> 生成前端 API + CRUD 页面');
+  process.exit(1);
+}
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--name' || a === '--model' || a === '--fields' || a === '--out') {
+      args[a.slice(2)] = argv[++i];
+    } else if (a.startsWith('--')) {
+      args[a.slice(2)] = true;
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function main(argv) {
+  const cmd = argv[0];
+  const rest = argv.slice(1);
+  const targetDir = process.cwd();
+  const args = parseArgs(rest);
+
+  switch (cmd) {
+    case 'ai:sync':
+      runSync(targetDir, path.join(targetDir, args.out || '.ai'));
+      break;
+
+    case 'ai:model': {
+      if (!args.name) {
+        console.error('  ✗ 缺少 --name（模块名，小写，如 demo）');
+        process.exit(1);
+      }
+      const modelName = args.model || args.name.charAt(0).toUpperCase() + args.name.slice(1);
+      generateModel({ targetDir, name: args.name, modelName, fieldsSpec: args.fields });
+      console.log('  ✅ 模型生成完成。可继续运行 ai:api 生成接口。');
+      break;
+    }
+
+    case 'ai:api': {
+      if (!args.name || !args.model) {
+        console.error('  ✗ 缺少 --name 或 --model');
+        process.exit(1);
+      }
+      generateApi({ targetDir, name: args.name, modelName: args.model });
+      console.log('  ✅ 接口生成完成。运行 pnpm doc 重新生成路由后重启服务即可生效。');
+      break;
+    }
+
+    case 'ai:vue-page': {
+      if (!args.name || !args.model) {
+        console.error('  ✗ 缺少 --name 或 --model');
+        process.exit(1);
+      }
+      generateVuePage({ targetDir, name: args.name, modelName: args.model });
+      console.log('  ✅ 前端页面生成完成。');
+      break;
+    }
+
+    default:
+      usage();
+  }
+}
+
+module.exports = main;
+
+// 直接执行（node ai.js ...）时自动运行
+if (require.main === module) {
+  main(process.argv.slice(2));
+}

package/bin/create-koa-boot.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+'use strict';
+require('../index.js');

package/index.js

@@ -0,0 +1,185 @@
+'use strict';
+/**
+ * create-koa-boot CLI
+ *
+ * 生成 koa-boot-runtime 项目脚手架：
+ *   1. 复制业务骨架模板（src/common、src/config、src/utils、src/business 等）
+ *   2. 合并 Prisma schema：
+ *      - 系统表片段：从 koa-boot-runtime/templates/schema.system.prisma 读取（单一事实来源）
+ *      - 业务表片段：CLI 内置 templates/prisma/schema.business.prisma
+ *   3. 生成 package.json / tsconfig / tsoa.json / .env.example 等
+ *
+ * 用法：
+ *   npx create-koa-boot <project-name>          # 纯后端骨架
+ *   npx create-koa-boot <project-name> --example # 三端完整示例（backend + frontend + uniapp）
+ */
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATE_DIR = path.join(__dirname, 'templates');
+
+// 复制时排除的目录/文件（生成物由用户项目自行产生）
+const SKIP_BASE = new Set(['node_modules', 'dist', 'build', '.git']);
+// 三端示例额外排除：本机 workaround 产物、构建产物、敏感配置
+const SKIP_EXAMPLE = new Set([
+  'node_modules', 'dist', 'build', '.git',
+  'vendor', 'unpackage', 'dev.log', 'package-lock.json',
+  '.env', '.env.development',
+]);
+
+function copyDir(src, dest, skip = SKIP_BASE) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (skip.has(entry.name)) continue;
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(s, d, skip);
+    } else {
+      fs.copyFileSync(s, d);
+    }
+  }
+}
+
+function mergeSchema(targetPrismaDir) {
+  // 系统表片段：从 koa-boot-runtime 包读取（保证与 runtime 版本一致）
+  let systemSchemaPath;
+  try {
+    systemSchemaPath = require.resolve('koa-boot-runtime/templates/schema.system.prisma');
+  } catch (err) {
+    // 本地开发（workspace）时兜底读取 runtime 仓库文件
+    const fallback = path.join(__dirname, '../runtime/templates/schema.system.prisma');
+    if (fs.existsSync(fallback)) {
+      systemSchemaPath = fallback;
+    } else {
+      throw new Error('未找到 koa-boot-runtime 的系统表 schema 片段，请先安装 koa-boot-runtime');
+    }
+  }
+  const systemSchema = fs.readFileSync(systemSchemaPath, 'utf8');
+  const businessSchemaPath = path.join(TEMPLATE_DIR, 'prisma', 'schema.business.prisma');
+  const businessSchema = fs.readFileSync(businessSchemaPath, 'utf8');
+
+  const merged = [
+    systemSchema.trimEnd(),
+    '',
+    '// ---------- 业务表（来自 create-koa-boot 模板，可按需追加） ----------',
+    '',
+    businessSchema.trimEnd(),
+    '',
+  ].join('\n');
+
+  const target = path.join(targetPrismaDir, 'schema.prisma');
+  fs.mkdirSync(targetPrismaDir, { recursive: true });
+  fs.writeFileSync(target, merged, 'utf8');
+  return merged;
+}
+
+// 三端示例的 backend/package.json 特化：
+//  - 项目名替换为 <project-name>-backend
+//  - runtime 依赖从本机 tarball（file:./vendor/...）改为 npm 包形式（^1.0.0）
+function patchExampleBackend(targetDir, projectName) {
+  const pkgPath = path.join(targetDir, 'backend', 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  pkg.name = `${projectName}-backend`;
+  if (!pkg.dependencies) pkg.dependencies = {};
+  pkg.dependencies['koa-boot-runtime'] = '^1.0.0';
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+}
+
+// AI 辅助命令（在已有 koa-boot 项目内运行）：ai:sync / ai:model / ai:api / ai:vue-page
+if (process.argv[2] && process.argv[2].startsWith('ai:')) {
+  require('./ai')(process.argv.slice(2));
+  return;
+}
+
+function parseArgs(argv) {
+  const projectName = argv.find((a) => !a.startsWith('-'));
+  if (!projectName) {
+    console.error('用法: create-koa-boot <project-name> [--example] [--skip-install]');
+    console.error('示例: create-koa-boot my-app');
+    console.error('      create-koa-boot my-app --example   # 三端完整示例（backend+frontend+uniapp）');
+    process.exit(1);
+  }
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9-_.]*$/.test(projectName)) {
+    console.error(`无效的项目名: "${projectName}"（仅允许字母、数字、- _ .，且不能以符号开头）`);
+    process.exit(1);
+  }
+  return {
+    projectName,
+    skipInstall: argv.includes('--skip-install'),
+    example: argv.includes('--example'),
+  };
+}
+
+function main() {
+  const { projectName, skipInstall, example } = parseArgs(process.argv.slice(2));
+  const targetDir = path.resolve(process.cwd(), projectName);
+
+  if (fs.existsSync(targetDir)) {
+    console.error(`目录已存在: ${targetDir}`);
+    process.exit(1);
+  }
+
+  if (example) {
+    console.log(`\n  ⚡ 正在生成 koa-boot 三端完整示例: ${projectName}\n`);
+
+    for (const sub of ['backend', 'frontend', 'uniapp']) {
+      copyDir(path.join(TEMPLATE_DIR, 'example', sub), path.join(targetDir, sub), SKIP_EXAMPLE);
+    }
+    if (fs.existsSync(path.join(TEMPLATE_DIR, 'example', 'AGENTS.md'))) {
+      fs.copyFileSync(path.join(TEMPLATE_DIR, 'example', 'AGENTS.md'), path.join(targetDir, 'AGENTS.md'));
+      console.log('  ✓ AGENTS.md（AI 开发规则）已生成');
+    }
+    console.log('  ✓ backend 模板已复制（koa-boot-runtime ^1.0.0）');
+    console.log('  ✓ frontend 模板已复制');
+    console.log('  ✓ uniapp 模板已复制（含 uni_modules 组件库）');
+
+    patchExampleBackend(targetDir, projectName);
+    console.log('  ✓ backend/package.json 已配置');
+
+    console.log('\n  ✅ 三端示例生成完成！下一步：\n');
+    console.log(`     cd ${projectName}`);
+    console.log('     pnpm install            # 或 npm install，安装全部依赖');
+    console.log('     # 后端：');
+    console.log('     cd backend && cp .env.example .env   # Windows: copy .env.example .env');
+    console.log('     编辑 .env 配置 DATABASE_URL（MySQL）后：');
+    console.log('     pnpm gen:types && pnpm db:push && pnpm dev');
+    console.log('     API 文档: http://localhost:3003/api-docs/business\n');
+    console.log('     # 前端（另开终端）：');
+    console.log('     cd frontend && pnpm dev\n');
+    console.log('     # uniapp：用 HBuilderX 打开 uniapp 目录启动预览\n');
+  } else {
+    console.log(`\n  ⚡ 正在生成 koa-boot 项目: ${projectName}\n`);
+
+    // 1. 复制模板（src/配置/脚本）
+    copyDir(TEMPLATE_DIR, targetDir);
+    console.log('  ✓ 业务骨架模板已复制');
+
+    // 2. 合并 Prisma schema
+    mergeSchema(path.join(targetDir, 'prisma'));
+    console.log('  ✓ Prisma schema 已合并（系统表 + 业务表）');
+
+    // 3. 替换 package.json 项目名
+    const pkgPath = path.join(targetDir, 'package.json');
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    pkg.name = projectName;
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf8');
+    console.log('  ✓ package.json 已生成');
+
+    // 4. 提示后续步骤
+    console.log('\n  ✅ 项目生成完成！下一步：\n');
+    console.log(`     cd ${projectName}`);
+    console.log('     npm install          # 或 pnpm install');
+    console.log('     编辑 .env 配置 DATABASE_URL（MySQL）后：');
+    console.log('     npx prisma db push   # 建表（自动创建 admin/admin123）');
+    console.log('     npm run dev          # 启动: http://localhost:3003');
+    console.log('     API 文档: http://localhost:3003/api-docs/business');
+    console.log('     系统文档: http://localhost:3003/api-docs/system\n');
+  }
+
+  if (skipInstall) {
+    console.log('  （已跳过自动安装，请手动 npm install）\n');
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "create-koa-boot",
+  "version": "1.0.0",
+  "description": "Scaffolding CLI: generate a koa-boot-runtime project with system routes, demo business modules and merged Prisma schema",
+  "bin": {
+    "create-koa-boot": "bin/create-koa-boot.js"
+  },
+  "main": "index.js",
+  "files": [
+    "bin",
+    "index.js",
+    "ai.js",
+    "ai",
+    "templates"
+  ],
+  "scripts": {
+    "test": "node tests/generate.test.js"
+  },
+  "engines": {
+    "node": ">=18.19.0"
+  },
+  "dependencies": {
+    "koa-boot-runtime": "^1.0.0"
+  },
+  "license": "MIT"
+}

package/templates/.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/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 路由 → 重启服务。