@ynight/create-app 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 diaogroup
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,202 @@
-# Temporary Holding Version
+# @ynight/create-app
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> 一行命令即可生成最小可运行的 Elpis 业务工程（zero-client 模板），专注于服务端的 Model、Controller、Service 与 DSL 配置。
+
+## 概述
+
+`@ynight/create-app` 是 Elpis 框架官方维护的 **最小业务工程脚手架**。它会把随包发布的 `templates/basic` 目录原样拷贝到指定目录，并对模板中预置的占位符进行批量替换（`__PROJECT_NAME__`、`__PACKAGE_NAME__`、`__PROJECT_TITLE__`、`__ELPIS_VERSION__`），随后按所选包管理器执行 `install`。
+
+生成出来的工程具有以下特点：
+
+- 已包含 `elpis.config.ts`、`server/app.ts`、`package.json`、`tsconfig.*.json` 等关键文件
+- 自带一个基于 **内存数据** 的「商品」示例 Controller / Router / Service，方便直接 `pnpm dev` 看效果
+- 提供一套基于 Model DSL 的「业务后台」菜单（商品列表 + 本地帮助 iframe），Schema 列表、搜索、CRUD 弹窗、Project List、Dashboard 全部由 `@ynight/framework/client` 提供
+- **不带任何 Vue/前端源码**（zero-client 模型），如需自定义控件或页面，可选地在 `types/empty-client.ts` 处按框架约定注册
+
+## 快速开始
+
+```bash
+# 使用 npx
+npx @ynight/create-app my-elpis-app
+
+# 或使用 pnpm
+pnpm dlx @ynight/create-app my-elpis-app
+```
+
+执行后会看到如下流程：
+
+1. 校验目标目录（必须不存在、为空目录或为符号链接以外的空目录）
+2. 将 `templates/basic` 拷贝到目标目录，并做占位符替换
+3. 除非传入了 `--skip-install`，否则调用所选包管理器在目标目录中执行 `install`
+4. 在终端打印「下一步」提示（开发命令、内存 Service 提醒、Basic Auth 提醒等）
+
+成功示例：
+
+```text
+Elpis 项目已创建: /Users/you/work/my-elpis-app
+开发: cd "/Users/you/work/my-elpis-app" && npm run dev
+提示：开发环境使用 devAnonymous，生产示例使用环境变量配置的 Basic Auth；示例 Service 使用内存数据，重启后数据会丢失。
+```
+
+## 参数与选项
+
+```text
+用法: create-elpis-app <目录> [--package-manager npm|pnpm] [--skip-install] [--yes]
+
+位置参数:
+  <目录>                                  目标工程目录（必须不存在或为空）
+
+选项:
+  --package-manager <npm|pnpm>            指定包管理器，默认 npm
+  --skip-install                          跳过依赖安装步骤
+  --yes                                   （当前版本作为保留位，与 --skip-install 共存解析，不影响结果）
+  --help, -h                              打印帮助信息
+  --version, -v                           打印版本号
+```
+
+如果传入未知参数或未提供目标目录，CLI 会以非零状态退出并打印错误信息，例如：
+
+```text
+创建失败: 请指定新项目目录
+创建失败: 目标目录必须不存在或为空，且不能是符号链接: /tmp/foo
+创建失败: --package-manager 只能是 npm 或 pnpm
+```
+
+## 模板结构
+
+`templates/basic` 是脚手架唯一内置的模板，目录布局如下（拷贝后会保留全部文件）：
+
+```text
+my-elpis-app/
+├── elpis.config.ts                       # 工程配置（server / model / public / build）
+├── package.json                          # 含 elpis dev / build / type-check / generate:types 脚本
+├── tsconfig.json                         # 根 tsconfig，仅做引用转发
+├── tsconfig.server.json                  # 后端 tsconfig：extends @ynight/cli/tsconfig/server.json
+├── tsconfig.client.json                  # 前端 tsconfig：仅 include types/empty-client.ts
+├── gitignore                             # 拷贝后被重命名为 .gitignore（node_modules / dist / .elpis / *.log）
+├── server/
+│   ├── app.ts                            # defineServer 入口：开启 devAnonymous、配置 Basic Auth 适配器
+│   ├── controller/
+│   │   └── product.ts                    # 示例 ProductController（继承 BaseController）
+│   ├── router/
+│   │   └── product.ts                    # 示例商品 REST 路由（list / create / detail / update / remove）
+│   └── service/
+│       └── product.ts                    # 示例 ProductService：继承 BaseService，数据保存在进程内存
+├── model/
+│   └── business/
+│       ├── model.ts                      # 业务模型定义：name / menu（schema + iframe）
+│       └── project/
+│           └── demo.ts                   # 演示项目：name / desc / homePage / menu 覆盖
+├── types/
+│   └── empty-client.ts                   # zero-client 占位：仅 export {}，供 vue-tsc 消费
+└── public/
+    ├── help.html                         # 供 iframe('help', ...) 引用的本地帮助页
+    └── .gitkeep                          # 保留 public 目录为空时的占位文件
+```
+
+拷贝后 `gitignore` 会被自动重命名为 `.gitignore`，避免 npm 发布的 tar 包忽略问题。
+
+## 模板工程做了什么
+
+模板工程刻意保持「最小可用」状态，关键边界如下，请在使用前先理解：
+
+### 1. zero-client 模型
+
+模板中 **不存在任何 Vue 源码**。`tsconfig.client.json` 只 `include` 一个空实现的 `types/empty-client.ts`，用来满足 `vue-tsc` 的强制类型入口需要。这意味着：
+
+| 能力                         | 由谁提供                                  |
+| ---------------------------- | ----------------------------------------- |
+| Schema 列表、搜索、CRUD 弹窗 | `@ynight/framework/client` 自带组件       |
+| Project List、Dashboard 壳层 | `@ynight/framework/client` 自带页面       |
+| 本地帮助 iframe 帮助页       | 用户工程 `public/help.html` 自提供        |
+| 自定义控件 / 自定义页面      | 用户按需在 `types/empty-client.ts` 中注册 |
+
+### 2. 业务示例源码属于用户工程
+
+`model/business/model.ts`、`model/business/project/demo.ts`、`server/controller/product.ts`、`server/router/product.ts`、`server/service/product.ts` **都是用户工程的实例源码**，不归属于任何 `@ynight/*` 框架包。你可以自由修改、删除或替换它们，框架包只负责提供运行时与默认壳层。
+
+### 3. 认证策略
+
+`server/app.ts` 通过 `defineServer` 注册：
+
+- `devAnonymous: true`：开发环境下跳过登录校验，方便直接调试
+- `auth.challenge = 'Basic realm="Elpis demo"'`、`authenticate` 读取 `Authorization: Basic …` 并比对 `ELPIS_DEMO_USERNAME` / `ELPIS_DEMO_PASSWORD`
+- `auth.authorize`：演示版始终返回 `true`
+
+**示例未实现完整的账号体系**（没有用户表、没有登录页、没有 Token 刷新）。正式项目应：
+
+- 把 `ELPIS_DEMO_USERNAME` / `ELPIS_DEMO_PASSWORD` 替换为真实的用户表查询
+- 在 `auth.authorize` 中按模块（`access.module`）和操作（`access.action`）做 RBAC 校验
+- 接入真正的会话、Token 或 SSO 方案
+
+### 4. 数据层
+
+`ProductService` 把数据保存在 `this.products` 数组中，**重启后恢复到只有一条「示例商品」的初始状态**。这是为了让 `pnpm dev` 起来就有数据可看，但 **绝对不能直接用于生产**。请把 `ProductService` 替换为对接数据库（MySQL / PostgreSQL / MongoDB / …）的实现。
+
+## 启动新工程
+
+```bash
+cd my-elpis-app
+pnpm dev
+```
+
+默认监听 `http://127.0.0.1:3000`（见 `elpis.config.ts` 的 `host` / `port`）。打开后会看到框架提供的 Project List 页面，「演示项目」即对应 `model/business/project/demo.ts`；点击进入后能看到商品列表、搜索、CRUD 操作以及左侧「本地使用帮助」iframe。
+
+## 后续步骤建议
+
+按顺序补齐以下内容即可上线：
+
+1. **替换数据层**：把 `server/service/product.ts` 改为对接真实数据库的实现；删掉或迁移 `this.products` 内存数组
+2. **替换认证**：在 `server/app.ts` 中改写 `auth.authenticate` 与 `auth.authorize`，或接入完整的 `auth` 适配器（OAuth / OIDC / 自研账号系统）
+3. **调整 DSL**：在 `model/business/model.ts` / `model/business/project/demo.ts` 中按真实业务改造菜单、表单、表格字段
+4. **（可选）扩展前端**：在 `types/empty-client.ts` 处注册自定义控件 / 自定义页面，参考 `@ynight/framework/client` 的扩展约定
+5. **配置 CI**：在 `.gitignore` 已经覆盖 `node_modules` / `dist` / `.elpis` / `*.log` 的基础上，按需补充 IDE / 操作系统相关条目
+
+## 常见问题
+
+### 目标目录已存在怎么办？
+
+CLI 会拒绝非空目录、符号链接目录或非目录路径，并抛出：
+
+```text
+创建失败: 目标目录必须不存在或为空，且不能是符号链接: /path/to/dir
+```
+
+请先清空目标目录，或换一个名字重新执行。
+
+### 想换包管理器怎么办？
+
+```bash
+npx @ynight/create-app my-app --package-manager pnpm
+# 或
+npx @ynight/create-app my-app --package-manager npm
+```
+
+未指定时默认使用 `npm`。
+
+### 不想立刻安装依赖怎么办？
+
+```bash
+npx @ynight/create-app my-app --skip-install
+```
+
+随后可以进入工程手动执行 `pnpm install` / `npm install` / `yarn install`。
+
+### 安装失败会保留工程吗？
+
+会。如果 `install` 阶段非零退出，目标工程会被保留在原位置，CLI 会提示在工程目录中重新执行依赖安装命令。
+
+## 相关包
+
+- [`@ynight/framework`](../framework) - 框架主入口，被生成的工程依赖（`dependencies`）
+- [`@ynight/cli`](../cli) - 提供 `elpis dev` / `elpis build` / `elpis type-check` / `elpis generate:types` 命令
+- [`@ynight/contracts`](../contracts) - DSL / 配置类型契约
+
+## 引擎要求
+
+- Node.js `>=22.0.0`
+- 包管理器：npm 或 pnpm（推荐 pnpm）
+
+## 许可证
+
+MIT

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const node_fs_1 = tslib_1.__importDefault(require("node:fs"));
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const VERSION = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.resolve(__dirname, '../package.json'), 'utf8')).version;
+const HELP = `创建 Elpis 管理后台
+
+用法: create-elpis-app <目录> [--package-manager npm|pnpm] [--skip-install] [--yes]`;
+function parseArgs(argv) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        return 'help';
+    }
+    if (argv.includes('--version') || argv.includes('-v')) {
+        return 'version';
+    }
+    const options = { packageManager: 'npm', skipInstall: false };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg && !arg.startsWith('-') && !options.target) {
+            options.target = arg;
+        }
+        else if (arg === '--package-manager') {
+            const manager = argv[++index];
+            if (manager !== 'npm' && manager !== 'pnpm') {
+                throw new Error('--package-manager 只能是 npm 或 pnpm');
+            }
+            options.packageManager = manager;
+        }
+        else if (arg === '--skip-install' || arg === '--yes') {
+            if (arg === '--skip-install') {
+                options.skipInstall = true;
+            }
+        }
+        else if (arg) {
+            throw new Error(`未知参数: ${arg}`);
+        }
+    }
+    if (!options.target) {
+        throw new Error('请指定新项目目录');
+    }
+    return options;
+}
+function normalizePackageName(projectName) {
+    const normalized = projectName
+        .normalize('NFKD')
+        .replace(/[^a-zA-Z0-9._-]+/g, '-')
+        .replace(/^[._-]+|[._-]+$/g, '')
+        .toLowerCase()
+        .slice(0, 214)
+        .replace(/^[._-]+|[._-]+$/g, '');
+    return normalized || 'elpis-app';
+}
+function replaceText(filePath, projectName, packageName) {
+    const stat = node_fs_1.default.statSync(filePath);
+    if (stat.isDirectory()) {
+        node_fs_1.default.readdirSync(filePath).forEach(name => replaceText(node_path_1.default.resolve(filePath, name), projectName, packageName));
+        return;
+    }
+    const content = node_fs_1.default
+        .readFileSync(filePath, 'utf8')
+        .replaceAll('__PROJECT_NAME__', projectName)
+        .replaceAll('__PACKAGE_NAME__', packageName)
+        .replaceAll('__PROJECT_TITLE__', JSON.stringify(`${projectName} 管理后台`))
+        .replaceAll('__ELPIS_VERSION__', VERSION);
+    node_fs_1.default.writeFileSync(filePath, content);
+}
+/** 删除模板中因移除可选扩展而留下的空目录。 */
+function removeEmptyDirectories(directory) {
+    node_fs_1.default.readdirSync(directory, { withFileTypes: true }).forEach(entry => {
+        if (entry.isDirectory()) {
+            const child = node_path_1.default.resolve(directory, entry.name);
+            removeEmptyDirectories(child);
+            if (node_fs_1.default.readdirSync(child).length === 0) {
+                node_fs_1.default.rmdirSync(child);
+            }
+        }
+    });
+}
+function createProject(options) {
+    const target = node_path_1.default.resolve(options.target);
+    if (node_fs_1.default.existsSync(target)) {
+        const stat = node_fs_1.default.lstatSync(target);
+        if (stat.isSymbolicLink() || !stat.isDirectory() || node_fs_1.default.readdirSync(target).length > 0) {
+            throw new Error(`目标目录必须不存在或为空，且不能是符号链接: ${target}`);
+        }
+    }
+    const parent = node_path_1.default.dirname(target);
+    node_fs_1.default.mkdirSync(parent, { recursive: true });
+    const temporary = node_fs_1.default.mkdtempSync(node_path_1.default.join(parent, '.elpis-create-'));
+    const template = node_path_1.default.resolve(__dirname, '../templates/basic');
+    try {
+        node_fs_1.default.cpSync(template, temporary, { recursive: true });
+        const packedGitignore = node_path_1.default.resolve(temporary, 'gitignore');
+        if (node_fs_1.default.existsSync(packedGitignore)) {
+            node_fs_1.default.renameSync(packedGitignore, node_path_1.default.resolve(temporary, '.gitignore'));
+        }
+        removeEmptyDirectories(temporary);
+        const projectName = node_path_1.default.basename(target);
+        replaceText(temporary, projectName, normalizePackageName(projectName));
+        if (node_fs_1.default.existsSync(target)) {
+            node_fs_1.default.rmdirSync(target);
+        }
+        node_fs_1.default.renameSync(temporary, target);
+    }
+    catch (error) {
+        node_fs_1.default.rmSync(temporary, { recursive: true, force: true });
+        throw error;
+    }
+    return target;
+}
+function install(target, packageManager) {
+    const command = packageManager === 'pnpm' ? 'pnpm' : 'npm';
+    const args = packageManager === 'pnpm' ? ['install'] : ['install'];
+    const result = (0, node_child_process_1.spawnSync)(command, args, { cwd: target, stdio: 'inherit' });
+    if (result.error || result.status !== 0) {
+        throw new Error(`依赖安装失败。项目已保留，请在 ${target} 中重新执行 ${command} install`);
+    }
+}
+function main() {
+    const parsed = parseArgs(process.argv.slice(2));
+    if (parsed === 'help') {
+        console.log(HELP);
+        return;
+    }
+    if (parsed === 'version') {
+        console.log(VERSION);
+        return;
+    }
+    const target = createProject(parsed);
+    if (!parsed.skipInstall) {
+        install(target, parsed.packageManager);
+    }
+    console.log(`Elpis 项目已创建: ${target}`);
+    console.log('开发: cd "' + target + '" && npm run dev');
+    console.log('提示：开发环境使用 devAnonymous，生产示例使用环境变量配置的 Basic Auth；示例 Service 使用内存数据，重启后数据会丢失。');
+}
+try {
+    main();
+}
+catch (error) {
+    console.error(`创建失败: ${error instanceof Error ? error.message : error}`);
+    process.exitCode = 1;
+}
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@ynight/create-app",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Elpis 业务工程脚手架",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@git.code.tencent.com/YNight/elpis.git"
+  },
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "create-elpis-app": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "rimraf": "^5.0.10",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "rimraf dist && tsc -p tsconfig.json",
+    "type-check": "tsc --noEmit -p tsconfig.json",
+    "lint": "eslint src"
+  }
 }

package/templates/basic/elpis.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from '@ynight/framework/server';
+
+export default defineConfig({
+  server: {
+    host: '127.0.0.1',
+    port: 3000,
+    entry: './server/app.ts',
+    businessDir: './server',
+  },
+  model: { dir: './model' },
+  // Model、Project 与业务接口均是此实例项目的源码；框架只提供运行时和默认壳层。
+  public: {
+    title: __PROJECT_TITLE__,
+    homePage: '/project-list',
+    projectListMode: 'never',
+    defaultProjectKey: 'demo',
+  },
+  build: { outDir: './dist' },
+});

package/templates/basic/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.elpis/
+*.log

package/templates/basic/model/business/model.ts

@@ -0,0 +1,139 @@
+import {
+  EventKey,
+  SchemaComponentName,
+  SchemaFormControlType,
+  defineModel,
+  iframe,
+  schema,
+} from '@ynight/framework/model';
+
+export default defineModel({
+  name: '业务后台',
+  mode: 'dashboard',
+  menu: [
+    schema('product-list', '商品列表', {
+      api: '/api/product',
+      schema: {
+        type: 'object',
+        properties: {
+          id: {
+            type: 'string',
+            label: '商品编号',
+            tableOption: { visible: false },
+          },
+          productName: {
+            type: 'string',
+            label: '商品名称',
+            minLength: 1,
+            tableOption: { visible: true },
+            searchOption: { comType: SchemaFormControlType.Input, visible: true },
+            CreateFormOption: { comType: SchemaFormControlType.Input, visible: true },
+            UpdateFormOption: { comType: SchemaFormControlType.Input, visible: true },
+            DetailViewOption: { visible: true },
+          },
+          price: {
+            type: 'number',
+            label: '价格',
+            minimum: 0,
+            tableOption: { visible: true, toFixed: 2 },
+            CreateFormOption: {
+              comType: SchemaFormControlType.InputNumber,
+              visible: true,
+              min: 0,
+              precision: 2,
+            },
+            UpdateFormOption: {
+              comType: SchemaFormControlType.InputNumber,
+              visible: true,
+              min: 0,
+              precision: 2,
+            },
+            DetailViewOption: { visible: true },
+          },
+          stock: {
+            type: 'number',
+            label: '库存',
+            minimum: 0,
+            tableOption: { visible: true },
+            CreateFormOption: {
+              comType: SchemaFormControlType.InputNumber,
+              visible: true,
+              min: 0,
+              precision: 0,
+            },
+            UpdateFormOption: {
+              comType: SchemaFormControlType.InputNumber,
+              visible: true,
+              min: 0,
+              precision: 0,
+            },
+            DetailViewOption: { visible: true },
+          },
+          status: {
+            type: 'string',
+            label: '状态',
+            oneOf: [
+              { const: 'on', title: '在售' },
+              { const: 'off', title: '下架' },
+            ],
+            tableOption: { visible: true, filter: true, filterMultiple: false },
+            searchOption: { comType: SchemaFormControlType.Select, visible: true },
+            CreateFormOption: { comType: SchemaFormControlType.Select, visible: true },
+            UpdateFormOption: { comType: SchemaFormControlType.Select, visible: true },
+            DetailViewOption: { visible: true },
+          },
+          createTime: {
+            type: 'string',
+            label: '创建时间',
+            tableOption: { visible: true },
+            DetailViewOption: { visible: true },
+          },
+        },
+      },
+      searchConfig: {},
+      tableConfig: {
+        headerButtons: [
+          {
+            label: '新增商品',
+            eventKey: EventKey.SHOW_COMPONENT,
+            eventOption: { comName: SchemaComponentName.CreateForm },
+            type: 'primary',
+          },
+        ],
+        rowButtons: [
+          {
+            label: '查看',
+            eventKey: EventKey.SHOW_COMPONENT,
+            eventOption: {
+              params: { id: 'schema::id' },
+              comName: SchemaComponentName.DetailView,
+            },
+            link: true,
+          },
+          {
+            label: '编辑',
+            eventKey: EventKey.SHOW_COMPONENT,
+            eventOption: {
+              params: { id: 'schema::id' },
+              comName: SchemaComponentName.UpdateForm,
+            },
+            link: true,
+          },
+          {
+            label: '删除',
+            eventKey: EventKey.DELETE,
+            eventOption: {},
+            type: 'danger',
+            link: true,
+          },
+        ],
+      },
+      components: {
+        CreateForm: { title: '新增商品', saveBtnText: '保存' },
+        UpdateForm: { title: '编辑商品', saveBtnText: '保存' },
+        DetailView: { title: '商品详情' },
+      },
+    }),
+    iframe('help', '本地使用帮助', '/help.html'),
+  ],
+});

package/templates/basic/model/business/project/demo.ts

@@ -0,0 +1,8 @@
+import { defineModel } from '@ynight/framework/model';
+
+export default defineModel({
+  name: '演示项目',
+  desc: '仅用于展示框架接入方式',
+  homePage: '/dashboard?projectKey=demo&key=product-list',
+  menu: [],
+});

package/templates/basic/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "__PACKAGE_NAME__",
+  "version": "0.0.1",
+  "private": true,
+  "type": "commonjs",
+  "scripts": {
+    "dev": "elpis dev",
+    "build": "elpis build",
+    "type-check": "elpis type-check",
+    "generate:types": "elpis generate:types",
+    "generate:types:check": "elpis generate:types --check",
+    "start": "node dist/server/index.js"
+  },
+  "dependencies": {
+    "@ynight/framework": "__ELPIS_VERSION__",
+    "element-plus": "^2.13.1",
+    "pinia": "^3.0.4",
+    "vue": "^3.5.26",
+    "vue-router": "^4.6.4"
+  },
+  "devDependencies": {
+    "@ynight/cli": "__ELPIS_VERSION__",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}

package/templates/basic/public/help.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>本地使用帮助</title>
+    <style>
+      body { margin: 0; padding: 32px; color: #24324a; font: 16px/1.7 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #f7f9fc; }
+      main { max-width: 720px; margin: 0 auto; padding: 28px; border: 1px solid #e4eaf2; border-radius: 12px; background: #fff; }
+      h1 { margin-top: 0; }
+      code { padding: 2px 6px; border-radius: 4px; background: #eef3f9; }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>本地使用帮助</h1>
+      <p>这是由脚手架生成的本地 iframe 页面，说明静态资源由业务项目自己提供。</p>
+      <p>商品数据保存在进程内存中，服务重启后会恢复为初始示例数据，生产环境请替换为数据库 Service。</p>
+    </main>
+  </body>
+</html>

package/templates/basic/server/app.ts

@@ -0,0 +1,34 @@
+import { timingSafeEqual } from 'node:crypto';
+import { defineServer, type AuthIdentity, type Context } from '@ynight/framework/server';
+
+function safeEqual(actual: string, expected: string): boolean {
+  const actualBytes = Buffer.from(actual);
+  const expectedBytes = Buffer.from(expected);
+  return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes);
+}
+
+function authenticate(ctx: Context): AuthIdentity | null {
+  const [scheme, encoded] = ctx.get('authorization').split(' ', 2);
+  if (scheme?.toLowerCase() !== 'basic' || !encoded) return null;
+  const decoded = Buffer.from(encoded, 'base64').toString('utf8');
+  const separator = decoded.indexOf(':');
+  const username = separator < 0 ? decoded : decoded.slice(0, separator);
+  const password = separator < 0 ? '' : decoded.slice(separator + 1);
+  const expectedUsername = process.env.ELPIS_DEMO_USERNAME;
+  const expectedPassword = process.env.ELPIS_DEMO_PASSWORD;
+  if (!expectedUsername || !expectedPassword) return null;
+  return safeEqual(username, expectedUsername) && safeEqual(password, expectedPassword)
+    ? { id: 'demo-admin', name: '演示管理员' }
+    : null;
+}
+
+export default defineServer({
+  devAnonymous: true,
+  auth: {
+    challenge: 'Basic realm="Elpis demo"',
+    authenticate,
+    authorize() {
+      return true;
+    },
+  },
+});

package/templates/basic/server/controller/product.ts

@@ -0,0 +1,72 @@
+import { BaseController } from '@ynight/framework/server';
+import type { Context } from '@ynight/framework/server';
+
+export default class ProductController extends BaseController {
+  list(ctx: Context) {
+    const service = this.app.service.product as { list(): unknown[] };
+    const data = service.list();
+    this.success(ctx, data, { total: data.length });
+  }
+
+  create(ctx: Context) {
+    const body = (ctx.request as typeof ctx.request & { body: unknown }).body as {
+      productName?: unknown;
+      price?: unknown;
+      stock?: unknown;
+      status?: unknown;
+    };
+    if (typeof body.productName !== 'string' || typeof body.price !== 'number') {
+      this.fail(ctx, '商品名称和价格不能为空', 400);
+      return;
+    }
+    const service = this.app.service.product as {
+      create(payload: {
+        productName: string;
+        price: number;
+        stock: number;
+        status: 'on' | 'off';
+      }): unknown;
+    };
+    this.success(
+      ctx,
+      service.create({
+        productName: body.productName,
+        price: body.price,
+        stock: typeof body.stock === 'number' ? body.stock : 0,
+        status: body.status === 'off' ? 'off' : 'on',
+      })
+    );
+  }
+
+  detail(ctx: Context) {
+    const service = this.app.service.product as { get(id: string): unknown };
+    const data = service.get(ctx.params.id);
+    if (!data) {
+      this.fail(ctx, '商品不存在', 404);
+      return;
+    }
+    this.success(ctx, data);
+  }
+
+  update(ctx: Context) {
+    const service = this.app.service.product as {
+      update(id: string, payload: Record<string, unknown>): unknown;
+    };
+    const body = (ctx.request as typeof ctx.request & { body: unknown }).body;
+    const data = service.update(ctx.params.id, body as Record<string, unknown>);
+    if (!data) {
+      this.fail(ctx, '商品不存在', 404);
+      return;
+    }
+    this.success(ctx, data);
+  }
+
+  remove(ctx: Context) {
+    const service = this.app.service.product as { remove(id: string): boolean };
+    if (!service.remove(ctx.params.id)) {
+      this.fail(ctx, '商品不存在', 404);
+      return;
+    }
+    this.success(ctx, { id: ctx.params.id });
+  }
+}

package/templates/basic/server/router/product.ts

@@ -0,0 +1,39 @@
+import { defineRoutes } from '@ynight/framework/server';
+import type { Context } from '@ynight/framework/server';
+
+export default defineRoutes(app => [
+  {
+    method: 'GET',
+    path: '/api/product',
+    access: { module: 'product', action: 'read' },
+    handler: (ctx: Context) => (app.controller.product as { list(ctx: Context): void }).list(ctx),
+  },
+  {
+    method: 'POST',
+    path: '/api/product',
+    access: { module: 'product', action: 'create' },
+    handler: (ctx: Context) =>
+      (app.controller.product as { create(ctx: Context): void }).create(ctx),
+  },
+  {
+    method: 'GET',
+    path: '/api/product/:id',
+    access: { module: 'product', action: 'read' },
+    handler: (ctx: Context) =>
+      (app.controller.product as { detail(ctx: Context): void }).detail(ctx),
+  },
+  {
+    method: 'PUT',
+    path: '/api/product/:id',
+    access: { module: 'product', action: 'update' },
+    handler: (ctx: Context) =>
+      (app.controller.product as { update(ctx: Context): void }).update(ctx),
+  },
+  {
+    method: 'DELETE',
+    path: '/api/product/:id',
+    access: { module: 'product', action: 'delete' },
+    handler: (ctx: Context) =>
+      (app.controller.product as { remove(ctx: Context): void }).remove(ctx),
+  },
+]);

package/templates/basic/server/service/product.ts

@@ -0,0 +1,56 @@
+import { BaseService } from '@ynight/framework/server';
+
+export default class ProductService extends BaseService {
+  private readonly products: Array<{
+    id: string;
+    productName: string;
+    price: number;
+    stock: number;
+    status: 'on' | 'off';
+    createTime: string;
+  }> = [
+    {
+      id: 'p-1',
+      productName: '示例商品',
+      price: 99,
+      stock: 10,
+      status: 'on',
+      createTime: new Date().toISOString(),
+    },
+  ];
+
+  list() {
+    return this.products;
+  }
+
+  create(payload: Omit<(typeof this.products)[number], 'id' | 'createTime'>) {
+    const product = {
+      ...payload,
+      id: `p-${this.products.length + 1}`,
+      createTime: new Date().toISOString(),
+    };
+    this.products.push(product);
+    return product;
+  }
+
+  get(id: string) {
+    return this.products.find(item => item.id === id);
+  }
+
+  update(id: string, payload: Record<string, unknown>) {
+    const product = this.get(id);
+    if (!product) return undefined;
+    if (typeof payload.productName === 'string') product.productName = payload.productName;
+    if (typeof payload.price === 'number') product.price = payload.price;
+    if (typeof payload.stock === 'number') product.stock = payload.stock;
+    if (payload.status === 'on' || payload.status === 'off') product.status = payload.status;
+    return product;
+  }
+
+  remove(id: string) {
+    const index = this.products.findIndex(item => item.id === id);
+    if (index < 0) return false;
+    this.products.splice(index, 1);
+    return true;
+  }
+}

package/templates/basic/tsconfig.client.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@ynight/cli/tsconfig/client.json",
+  "include": ["types/empty-client.ts"]
+}

package/templates/basic/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@ynight/cli/tsconfig/server.json",
+  "compilerOptions": { "rootDir": ".", "outDir": ".elpis/build/app" },
+  "include": ["elpis.config.ts", "server/**/*.ts", "model/**/*.ts", ".elpis/types/**/*.d.ts"],
+  "exclude": ["client", "dist", ".elpis/build"]
+}

package/templates/basic/tsconfig.server.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@ynight/cli/tsconfig/server.json",
+  "compilerOptions": { "rootDir": ".", "outDir": ".elpis/build/app" },
+  "include": ["elpis.config.ts", "server/**/*.ts", "model/**/*.ts", ".elpis/types/**/*.d.ts"],
+  "exclude": ["client", "dist", ".elpis/build"]
+}

package/templates/basic/types/empty-client.ts

@@ -0,0 +1,2 @@
+/** zero-client 项目没有 Vue 源码；此文件仅给无条件执行的 vue-tsc 提供类型输入。 */
+export {};