create-koa-boot 1.0.2 → 1.0.4

package/README.md

@@ -0,0 +1,110 @@
+# create-koa-boot
+
+基于 Koa 3 + Prisma + tsoa 的 **AI 驱动全栈框架**脚手架 CLI。
+
+一键生成全栈工程，内置 **AI 辅助命令**（`ai:sync` / `ai:model` / `ai:api` / `ai:vue-page`）：AI 通过扫描项目生成 `.ai/` 元数据理解代码库，再一键生成后端模型、CRUD 接口与前端页面，形成"AI 读懂项目 → 按规范生成 → 人工审核微调"的落地工作流。
+
+## 快速开始
+
+### 交互式（推荐，create-vue 风格）
+
+```bash
+npx create-koa-boot
+```
+
+按提示依次选择即可：
+
+```bash
+? Project name (my-app): my-app
+? Include Vue 3 + Element Plus frontend? (Y/n): Yes
+? Include uniapp mobile app? (y/N): No
+? Auto install dependencies? (y/N): No
+```
+
+- 后端（Koa 3）**始终生成**，前端 / uniapp 按需勾选；
+- 选 `Auto install dependencies` 会自动安装依赖（自动检测 pnpm / npm）。
+
+### 非交互（脚本 / CI）
+
+```bash
+npx create-koa-boot my-app            # 纯后端骨架
+npx create-koa-boot my-app --example  # 三端完整示例（backend + frontend + uniapp）
+```
+
+生成后：
+
+```bash
+cd my-app
+npm install
+# 编辑 .env 配置 DATABASE_URL（MySQL），然后：
+npx prisma db push    # 建表（首次启动自动创建 admin/admin123）
+npm run dev           # http://localhost:3003
+```
+
+生成项目的端点：
+
+- 系统文档：`http://localhost:3003/api-docs/system`
+- 业务文档：`http://localhost:3003/api-docs/business`
+- 登录：`POST /api/system/user/login`（`admin` / `admin123`）
+
+## AI 辅助命令
+
+在**已有项目根目录**执行（`npx create-koa-boot ai:*`）：
+
+| 命令 | 作用 |
+| --- | --- |
+| `ai:sync` | 扫描项目生成 `.ai/` 元数据（`entities.json` 模型清单 / `api-list.json` 接口清单 / `permissions.json` 权限清单），供 AI 理解代码库 |
+| `ai:model --name <m> --model <M> [--fields "f:t,f2:t?"]` | 生成业务模型 + DTO（Create 必填中文校验 / Update 全可选，`?` 后缀生成可选字段） |
+| `ai:api --name <m> --model <M>` | 生成 tsoa controller + service（CRUD + 搜索 + 分页六件套，遵循框架规范） |
+| `ai:vue-page --name <m> --model <M>` | 生成前端 API 封装 + CRUD 页面（Element Plus，定位到 `frontend/src/`） |
+
+示例：
+
+```bash
+create-koa-boot ai:sync
+create-koa-boot ai:model --name product --model Product --fields "name:string,price:int,stock:int?"
+create-koa-boot ai:api --name product --model Product
+create-koa-boot ai:vue-page --name product --model Product
+```
+
+**推荐工作流**：
+
+1. 先 `ai:sync` 刷新 `.ai/` 元数据；
+2. AI 依据 `.ai/entities.json` 理解模型，用 `ai:model` / `ai:api` / `ai:vue-page` 生成代码；
+3. 复杂业务手写时，严格参照 `src/business/demo/` 蓝本（模型校验、分页、响应包装、异常处理）。
+
+生成项目自带 `AGENTS.md`（AI 开发规则），约束 AI 的目录约定、分层规范、权限模型与代码风格；修改 Prisma schema 后运行 `pnpm gen:types` → `pnpm db:push`，新增 controller 后运行 `pnpm doc` 重新生成路由。
+
+## 生成的项目结构
+
+```
+my-app/
+├── backend/               # Koa 3 + tsoa 后端（--example 时）
+│   ├── prisma/schema.prisma  # 合并后的 Schema（系统 15 表 + 业务表）
+│   └── src/
+│       ├── business/      # 业务模块（demo 为蓝本）
+│       ├── init/          # 初始化种子（菜单/权限）
+│       └── build/         # 生成的 swagger.json / routes
+├── frontend/              # Vue 3 + Element Plus + Vite 前端（--example 时）
+├── uniapp/                # 移动端（--example 时）
+└── .ai/                   # ai:sync 生成的元数据（entities/api-list/permissions）
+```
+
+## 技术栈
+
+- **运行时**：Koa 3 + @koa/router + tsoa 6.6（OpenAPI 代码生成）
+- **ORM**：Prisma 5.19（MySQL）
+- **认证**：JWT + RBAC 角色权限（DB 表 `sys_permissions` 路径匹配）
+- **缓存/队列**：Redis（可降级）
+- **前端**：Vue 3 + Element Plus + Vite + Pinia + axios
+- **语言**：TypeScript 5.9
+
+## 环境要求
+
+- Node.js >= 18.19
+- MySQL 8.x（运行时数据）
+- Redis（可选，缺失时自动降级）
+
+## 相关
+
+- 运行时核心：`koa-boot-runtime`

package/index.js

@@ -10,16 +10,19 @@
  *   3. 生成 package.json / tsconfig / tsoa.json / .env.example 等
  *
  * 用法：
- *   npx create-koa-boot <project-name>          # 纯后端骨架
- *   npx create-koa-boot <project-name> --example # 三端完整示例（backend + frontend + uniapp）
+ *   create-koa-boot                          # 交互式（create-vue 风格提问）
+ *   create-koa-boot <project-name>           # 纯后端骨架
+ *   create-koa-boot <project-name> --example # 三端完整示例（backend + frontend + uniapp）
  */
 const fs = require('fs');
 const path = require('path');
+const { spawnSync } = require('child_process');
+const { runInteractive, c } = require('./interactive');
 
 const TEMPLATE_DIR = path.join(__dirname, 'templates');
 
-// 复制时排除的目录/文件（生成物由用户项目自行产生）
-const SKIP_BASE = new Set(['node_modules', 'dist', 'build', '.git']);
+// 复制时排除的目录/文件（生成物由用户项目自行产生；example 仅 --example/交互选择时单独复制）
+const SKIP_BASE = new Set(['node_modules', 'dist', 'build', '.git', 'example']);
 // 三端示例额外排除：本机 workaround 产物、构建产物、敏感配置
 const SKIP_EXAMPLE = new Set([
   'node_modules', 'dist', 'build', '.git',
@@ -111,8 +114,72 @@ function parseArgs(argv) {
   };
 }
 
-function main() {
-  const { projectName, skipInstall, example } = parseArgs(process.argv.slice(2));
+// 自动安装依赖：优先 pnpm，其次 npm（检测本机可用性）
+function runInstall(targetDir) {
+  const detect = (cmd) => {
+    const r = spawnSync(cmd, ['--version'], { shell: true, stdio: 'ignore' });
+    return !r.error && r.status === 0;
+  };
+  const pm = detect('pnpm') ? 'pnpm' : 'npm';
+  console.log(`\n  ⚡ 正在使用 ${pm} 安装依赖（可能需要几分钟）...\n`);
+  const r = spawnSync(pm, ['install'], { cwd: targetDir, shell: true, stdio: 'inherit' });
+  if (r.error || r.status !== 0) {
+    console.log(`\n  ${c.red('✖')} 自动安装失败，请手动执行：`);
+    console.log(`     cd ${path.basename(targetDir)}`);
+    console.log(`     ${pm} install\n`);
+  } else {
+    console.log(`\n  ${c.green('✓')} 依赖安装完成\n`);
+  }
+  return pm;
+}
+
+// 按选择的端打印后续步骤（useSubdir=true 表示三端布局，后端在 backend/ 子目录）
+function printNextSteps(opts) {
+  const { projectName, frontend, uniapp, pm, useSubdir } = opts;
+  console.log('\n  ✅ 项目生成完成！下一步：\n');
+  console.log(`     cd ${projectName}`);
+  console.log(`     ${pm} install            # 或 npm install，安装全部依赖`);
+  if (useSubdir) {
+    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');
+  } else {
+    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 (frontend) {
+    console.log('     # 前端（另开终端）：');
+    console.log('     cd frontend && pnpm dev   # http://localhost:5175\n');
+  }
+  if (uniapp) {
+    console.log('     # uniapp：用 HBuilderX 打开 uniapp 目录启动预览\n');
+  }
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+
+  // 无参数 → 交互式（create-vue 风格）
+  let opts;
+  if (argv.length === 0) {
+    const ans = await runInteractive();
+    opts = {
+      projectName: ans.projectName,
+      frontend: ans.frontend,
+      uniapp: ans.uniapp,
+      autoInstall: ans.autoInstall,
+      skipInstall: false,
+    };
+  } else {
+    opts = parseArgs(argv);
+  }
+
+  const { projectName, skipInstall, example = false, frontend = false, uniapp = false, autoInstall = false } = opts;
   const targetDir = path.resolve(process.cwd(), projectName);
 
   if (fs.existsSync(targetDir)) {
@@ -120,34 +187,30 @@ function main() {
     process.exit(1);
   }
 
-  if (example) {
-    console.log(`\n  ⚡ 正在生成 koa-boot 三端完整示例: ${projectName}\n`);
+  // --example 等价于「后端 + 前端 + uniapp」全选
+  const withExample = example || frontend || uniapp;
+
+  if (withExample) {
+    console.log(`\n  ⚡ 正在生成 koa-boot 项目: ${projectName}\n`);
+
+    copyDir(path.join(TEMPLATE_DIR, 'example', 'backend'), path.join(targetDir, 'backend'), SKIP_EXAMPLE);
+    console.log('  ✓ backend 模板已复制（koa-boot-runtime ^1.0.0）');
 
-    for (const sub of ['backend', 'frontend', 'uniapp']) {
-      copyDir(path.join(TEMPLATE_DIR, 'example', sub), path.join(targetDir, sub), SKIP_EXAMPLE);
+    if (frontend || example) {
+      copyDir(path.join(TEMPLATE_DIR, 'example', 'frontend'), path.join(targetDir, 'frontend'), SKIP_EXAMPLE);
+      console.log('  ✓ frontend 模板已复制（Vue 3 + Element Plus）');
+    }
+    if (uniapp || example) {
+      copyDir(path.join(TEMPLATE_DIR, 'example', 'uniapp'), path.join(targetDir, 'uniapp'), SKIP_EXAMPLE);
+      console.log('  ✓ uniapp 模板已复制（含 uni_modules 组件库）');
     }
     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`);
 
@@ -165,21 +228,25 @@ function main() {
     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');
   }
 
+  let pm = 'pnpm';
   if (skipInstall) {
     console.log('  （已跳过自动安装，请手动 npm install）\n');
+  } else if (autoInstall) {
+    pm = runInstall(targetDir);
   }
+
+  printNextSteps({
+    projectName,
+    frontend: frontend || example,
+    uniapp: uniapp || example,
+    pm,
+    useSubdir: withExample,
+  });
 }
 
-main();
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/interactive.js

@@ -0,0 +1,112 @@
+'use strict';
+/**
+ * create-koa-boot 交互式提示（create-vue 风格）
+ *
+ * 零依赖实现：基于 Node 内置 readline。
+ * 仅在「无参数」运行时启用；带参数运行走原有非交互逻辑。
+ *
+ * 实现说明：采用「行队列」模型——所有到达的输入行先入队，
+ * 每个问题从队列取一行消费，避免一次性 stdin（管道/脚本）下
+ * readline 同步派发行而 await 恢复滞后导致丢行的问题。
+ */
+
+const readline = require('readline');
+
+// 轻量 ANSI 颜色（Windows Terminal / PowerShell 7+ 均支持）
+const c = {
+  cyan: (s) => `\x1b[36m${s}\x1b[39m`,
+  green: (s) => `\x1b[32m${s}\x1b[39m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[39m`,
+  red: (s) => `\x1b[31m${s}\x1b[39m`,
+};
+
+function createInterface() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const lines = []; // 已到达、待消费的输入行
+  const pending = []; // 等待输入的问题回调（参数为行内容，null 表示 EOF）
+  let closed = false;
+
+  rl.on('line', (l) => {
+    const cb = pending.shift();
+    if (cb) cb(l);
+    else lines.push(l);
+  });
+  rl.on('close', () => {
+    closed = true;
+    while (pending.length) pending.shift()(null); // EOF：未答问题取默认值
+  });
+
+  return { rl, lines, pending, closed: () => closed };
+}
+
+/** 取一行输入：优先消费缓冲行，否则注册等待；EOF/关闭时返回 defaultValue */
+function nextLine(io, promptText, defaultValue) {
+  return new Promise((resolve) => {
+    if (io.closed()) return resolve(defaultValue);
+    if (io.lines.length) {
+      process.stdout.write(promptText);
+      return resolve(io.lines.shift());
+    }
+    process.stdout.write(promptText);
+    io.pending.push((l) => resolve(l === null ? defaultValue : l));
+  });
+}
+
+/** 文本输入：返回用户输入；空输入取默认值；validate 返回错误文案时重新询问 */
+async function askText(io, question, defaultValue, validate) {
+  const suffix = defaultValue ? ` ${c.cyan(`(${defaultValue})`)}` : '';
+  const prompt = `  ${c.cyan('?')} ${question}${suffix}: `;
+  for (;;) {
+    const line = await nextLine(io, prompt, defaultValue);
+    const val = (line || '').trim() || defaultValue;
+    if (validate) {
+      const err = validate(val);
+      if (err) {
+        console.log(`  ${c.red('✖')} ${err}`);
+        continue;
+      }
+    }
+    return val;
+  }
+}
+
+/** 确认输入：y/n/回车（默认值）；返回 boolean */
+async function askConfirm(io, question, defaultYes) {
+  const hint = defaultYes ? '(Y/n)' : '(y/N)';
+  const prompt = `  ${c.cyan('?')} ${question} ${c.yellow(hint)}: `;
+  for (;;) {
+    const line = await nextLine(io, prompt, defaultYes ? 'y' : 'n');
+    const a = (line || '').trim().toLowerCase();
+    if (a === 'y' || a === 'yes') return true;
+    if (a === 'n' || a === 'no') return false;
+    if (!a) return defaultYes;
+    // 无效输入：重新询问
+  }
+}
+
+/**
+ * 交互式提问主流程，返回：
+ * { projectName, frontend, uniapp, autoInstall }
+ */
+async function runInteractive() {
+  const io = createInterface();
+  try {
+    const projectName = await askText(io, 'Project name', 'my-app', (v) => {
+      if (!/^[a-zA-Z0-9][a-zA-Z0-9-_.]*$/.test(v)) {
+        return '仅允许字母、数字、- _ .，且不能以符号开头';
+      }
+      return null;
+    });
+    const frontend = await askConfirm(io, 'Include Vue 3 + Element Plus frontend?', true);
+    const uniapp = await askConfirm(io, 'Include uniapp mobile app?', false);
+    const autoInstall = await askConfirm(io, 'Auto install dependencies?', false);
+    return { projectName, frontend, uniapp, autoInstall };
+  } finally {
+    io.rl.close();
+  }
+}
+
+module.exports = { runInteractive, askText, askConfirm, c };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-koa-boot",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Scaffolding CLI: generate a koa-boot-runtime project with system routes, demo business modules and merged Prisma schema",
   "keywords": [
     "koa",
@@ -26,6 +26,7 @@
   "files": [
     "bin",
     "index.js",
+    "interactive.js",
     "ai.js",
     "ai",
     "templates"