create-koa-boot 1.0.1 → 1.0.3

package/README.md

@@ -0,0 +1,85 @@
+# create-koa-boot
+
+基于 Koa 3 + Prisma + tsoa 的 **AI 驱动全栈框架**脚手架 CLI。
+
+一键生成全栈工程，内置 **AI 辅助命令**（`ai:sync` / `ai:model` / `ai:api` / `ai:vue-page`）：AI 通过扫描项目生成 `.ai/` 元数据理解代码库，再一键生成后端模型、CRUD 接口与前端页面，形成"AI 读懂项目 → 按规范生成 → 人工审核微调"的落地工作流。
+
+## 快速开始
+
+```bash
+npx create-koa-boot my-app            # 纯后端骨架
+npx create-koa-boot my-app --example  # 三端完整示例（backend + frontend + uniapp）
+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/package.json

@@ -1,7 +1,24 @@
 {
   "name": "create-koa-boot",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Scaffolding CLI: generate a koa-boot-runtime project with system routes, demo business modules and merged Prisma schema",
+  "keywords": [
+    "koa",
+    "koa3",
+    "node",
+    "typescript",
+    "scaffold",
+    "cli",
+    "codegen",
+    "prisma",
+    "tsoa",
+    "fullstack",
+    "vue",
+    "admin",
+    "ai",
+    "code-generator",
+    "low-code"
+  ],
   "bin": {
     "create-koa-boot": "bin/create-koa-boot.js"
   },