create-lumfall 1.0.0 → 1.1.1

package/templates/basic/app/pages/home/home.vue

@@ -1,164 +0,0 @@
-<template>
-  <main class="home-page">
-    <section class="hero">
-      <h1 class="hero-title">Lumfall Basic Project</h1>
-      <p class="hero-desc">
-        基于 lumfall 的基础业务项目骨架。这个页面演示了：页面入口约定、
-        $lumfallCurl 调用 /api 接口、参数校验与统一响应结构。
-      </p>
-      <div class="hero-links">
-        <a-button type="primary" @click="goHealth">健康检查页</a-button>
-        <a-button @click="loadData">刷新数据</a-button>
-      </div>
-    </section>
-
-    <a-card class="panel" title="服务端配置（GET /api/demo/info）">
-      <a-descriptions :column="1" size="medium" v-if="info">
-        <a-descriptions-item label="应用名">{{ info.appName }}</a-descriptions-item>
-        <a-descriptions-item label="demoMessage">
-          <a-tag color="arcoblue">{{ info.demoMessage }}</a-tag>
-        </a-descriptions-item>
-        <a-descriptions-item label="服务端时间">{{ info.serverTime }}</a-descriptions-item>
-      </a-descriptions>
-    </a-card>
-
-    <a-card class="panel" title="笔记列表（GET /api/demo/note/list）">
-      <template #extra>
-        <a-space>
-          <a-input-search
-            v-model="newNote"
-            placeholder="输入内容，回车新建笔记"
-            style="width: 260px"
-            @search="handleCreate"
-            allow-clear
-          />
-        </a-space>
-      </template>
-
-      <a-table
-        :data="noteList"
-        :loading="loading"
-        :pagination="pagination"
-        size="medium"
-      >
-        <template #columns>
-          <a-table-column title="ID" data-index="id" :width="80" />
-          <a-table-column title="内容" data-index="content" />
-          <a-table-column title="创建时间" data-index="createdAt" :width="200" />
-        </template>
-      </a-table>
-    </a-card>
-  </main>
-</template>
-
-<script setup>
-import { computed, onMounted, ref } from "vue";
-import { Message } from "@arco-design/web-vue";
-import $curl from "$lumfallCurl";
-
-const info = ref(null);
-const noteList = ref([]);
-const loading = ref(false);
-const newNote = ref("");
-const total = ref(0);
-const currentPage = ref(1);
-const pageSize = ref(10);
-
-const pagination = computed(() => ({
-  total: total.value,
-  current: currentPage.value,
-  pageSize: pageSize.value,
-  showTotal: true,
-}));
-
-async function loadInfo() {
-  const res = await $curl({ method: "get", url: "/api/demo/info" });
-  if (res && res.success) {
-    info.value = res.data;
-  }
-}
-
-async function loadNoteList() {
-  loading.value = true;
-  const res = await $curl({
-    method: "get",
-    url: "/api/demo/note/list",
-    query: {
-      page: String(currentPage.value),
-      pageSize: String(pageSize.value),
-    },
-  });
-  loading.value = false;
-  if (res && res.success) {
-    noteList.value = res.data;
-    total.value = res.metadata.total;
-  }
-}
-
-async function handleCreate() {
-  const content = newNote.value.trim();
-  if (!content) {
-    Message.warning("请输入笔记内容");
-    return;
-  }
-
-  const res = await $curl({
-    method: "post",
-    url: "/api/demo/note",
-    data: { content },
-  });
-  if (res && res.success) {
-    newNote.value = "";
-    Message.success("创建成功");
-    currentPage.value = 1;
-    await loadNoteList();
-  }
-}
-
-function loadData() {
-  loadInfo();
-  loadNoteList();
-}
-
-function goHealth() {
-  window.location.href = "/view/health";
-}
-
-onMounted(loadData);
-</script>
-
-<style lang="less" scoped>
-.home-page {
-  box-sizing: border-box;
-  max-width: 960px;
-  margin: 0 auto;
-  padding: 48px 24px 64px;
-
-  .hero {
-    margin-bottom: 32px;
-
-    .hero-title {
-      margin: 0 0 12px;
-      font-size: 32px;
-      font-weight: 700;
-      color: var(--color-text-1);
-    }
-
-    .hero-desc {
-      margin: 0 0 20px;
-      font-size: 15px;
-      line-height: 1.8;
-      color: var(--color-text-2);
-    }
-
-    .hero-links {
-      display: flex;
-      gap: 12px;
-    }
-  }
-
-  .panel {
-    margin-bottom: 20px;
-  }
-}
-</style>

package/templates/basic/app/router/demo.js

@@ -1,17 +0,0 @@
-// 路由只负责把 URL 绑到 controller 方法。
-// 注意绑定时要 .bind(controller)，否则方法内的 this 会丢失。
-module.exports = (app, router) => {
-  const { demo: demoController } = app.controllers;
-
-  router.get("/api/demo/info", demoController.getInfo.bind(demoController));
-
-  router.get(
-    "/api/demo/note/list",
-    demoController.getNoteList.bind(demoController)
-  );
-
-  router.post(
-    "/api/demo/note",
-    demoController.createNote.bind(demoController)
-  );
-};

package/templates/basic/app/router-schema/demo.js

@@ -1,29 +0,0 @@
-// API 参数校验：key 必须是已注册路由的 path，method 必须全小写，否则启动失败。
-// 只作用于 /api 开头的请求；校验失败返回 HTTP 200 + { success: false, code: 442 }。
-module.exports = {
-  "/api/demo/info": {
-    get: {},
-  },
-  "/api/demo/note/list": {
-    get: {
-      query: {
-        type: "object",
-        properties: {
-          page: { type: "string" },
-          pageSize: { type: "string" },
-        },
-      },
-    },
-  },
-  "/api/demo/note": {
-    post: {
-      body: {
-        type: "object",
-        properties: {
-          content: { type: "string", minLength: 1, maxLength: 200 },
-        },
-        required: ["content"],
-      },
-    },
-  },
-};

package/templates/basic/app/service/demo.js

@@ -1,51 +0,0 @@
-// 示例 service：演示「工厂返回 class、继承 BaseService」的约定。
-// 文件名 demo.js + 无子目录 → 挂载到 app.services.demo
-// 数据放在内存里，重启即清空；真实业务请换成数据库 / 远程服务调用。
-module.exports = (app) => {
-  const BaseService = require("lumfall").Service.Base(app);
-
-  // 内存数据池
-  const notePool = [
-    { id: 1, content: "第一条示例笔记：这是一个基于 lumfall 的基础项目骨架", createdAt: "2026-10-02 10:00:00" },
-    { id: 2, content: "在 app/service 下新建文件即可被自动加载", createdAt: "2026-10-02 10:01:00" },
-    { id: 3, content: "配置通过 config/config.<env>.js 按 _ENV 合并", createdAt: "2026-10-02 10:02:00" },
-  ];
-  let nextId = notePool.length + 1;
-
-  return class DemoService extends BaseService {
-    // 请求阶段读 this.config（= app.config）是安全的；
-    // 不要在工厂执行期或构造期读，那时 configLoader 还没跑
-    getInfo() {
-      return {
-        appName: this.config.name,
-        demoMessage: this.config.demoMessage,
-        serverTime: new Date().toISOString(),
-      };
-    }
-
-    /**
-     * 分页查询笔记
-     * @param {{ page: number, size: number }} param0
-     */
-    getNoteList({ page = 1, size = 10 }) {
-      const start = (page - 1) * size;
-      const data = notePool.slice(start, start + size).map((note) => ({ ...note }));
-
-      return { data, total: notePool.length, page, size };
-    }
-
-    /**
-     * 新建笔记
-     * @param {{ content: string }} param0
-     */
-    createNote({ content }) {
-      const note = {
-        id: nextId++,
-        content,
-        createdAt: new Date().toISOString().slice(0, 19).replace("T", " "),
-      };
-      notePool.unshift(note);
-      return note;
-    }
-  };
-};

package/templates/basic/app/webpack.config.js

@@ -1,4 +0,0 @@
-// 业务 Webpack 扩展配置：与框架基础配置 webpack-merge.merge.smart 合并。
-// 例如给 .md 文件加 raw 导入：
-//   module.exports = { module: { rules: [{ test: /\.md$/, type: "asset/source" }] } };
-module.exports = {};

package/templates/basic/build.js

@@ -1,7 +0,0 @@
-const { frontendBuild } = require("lumfall");
-
-// 环境由 _ENV 决定（不是 NODE_ENV）：
-//   _ENV=local  启动 Webpack dev server（HMR 热更新，默认 127.0.0.1:9002）
-//   _ENV=prod   产物构建到 app/public/dist/prod/，同时产出各页面 .tpl 模板
-// 其他值（如 beta）不执行任何构建
-frontendBuild(process.env._ENV);

package/templates/basic/config/config.beta.js

@@ -1,4 +0,0 @@
-// _ENV=beta 时加载，覆盖 config.default.js 的同名键（浅合并）
-module.exports = {
-  demoMessage: "hello from beta config",
-};

package/templates/basic/config/config.default.js

@@ -1,32 +0,0 @@
-// 所有环境共享的基础配置。合并顺序（后者覆盖前者同名键）：
-//   框架 config.default -> 业务 config.default -> 框架 config.<env> -> 业务 config.<env>
-// 环境由 _ENV 决定（local / beta / prod，缺省 local），不是 NODE_ENV。
-module.exports = {
-  // 应用名，与 server.js 的 name 保持一致
-  name: "lumfall-basic-project",
-
-  // API 路径前缀约定：框架的参数校验（apiParamsVerify）与安全策略（securityPolicy）
-  // 只作用于 /api 开头的请求
-  apiBasePath: "/api",
-
-  // 示例配置：演示「配置如何从服务端流动到接口/页面」，各环境文件里都有同名键
-  demoMessage: "hello from config.default",
-
-  // 安全策略（可选）。不配置这段时，框架等价于「接口签名关闭 + projectKey 开启」
-  security: {
-    // 接口签名校验：开启后 /api 请求必须携带 s_sign = md5(secret + "_" + st)、
-    // st = 毫秒时间戳（前端 $lumfallCurl 默认带的是 s_sign / s_t，均可识别），
-    // 时间差超过 maxAgeMs 或时间戳在未来都会返回 code 445。
-    // 生产开启时 secret 建议走环境变量 / 配置中心，不要提交到仓库。
-    apiSignature: {
-      enabled: false,
-      maxAgeMs: 600000,
-    },
-    // project_key 校验：只作用于 /api/project/ 路径，缺 header 返回 code 446。
-    // /api/project/model_list、/api/project/list 内置豁免，可用 freePaths 追加。
-    projectKey: {
-      enabled: true,
-      headerName: "project_key",
-    },
-  },
-};

package/templates/basic/config/config.local.js

@@ -1,4 +0,0 @@
-// _ENV=local 时加载，覆盖 config.default.js 的同名键（浅合并）
-module.exports = {
-  demoMessage: "hello from local config",
-};

package/templates/basic/config/config.prod.js

@@ -1,6 +0,0 @@
-// _ENV=prod 时加载，覆盖 config.default.js 的同名键（浅合并）。
-// 生产相关的密钥、连接串建议从环境变量读取：
-//   module.exports = { dbPassword: process.env.DB_PASSWORD };
-module.exports = {
-  demoMessage: "hello from prod config",
-};

package/templates/basic/package.json

@@ -1,31 +0,0 @@
-{
-  "name": "lumfall-basic-project",
-  "version": "1.0.0",
-  "description": "基于 lumfall 的基础业务项目骨架：目录约定、示例 API 与示例页面，开箱即用",
-  "main": "server.js",
-  "scripts": {
-    "dev": "_ENV='local' nodemon --exitcrash server.js",
-    "beta": "_ENV='beta' nodemon --exitcrash server.js",
-    "prod": "_ENV='prod' node server.js",
-    "build:dev": "_ENV='local' node --max_old_space_size=4096 ./build.js",
-    "build:prod": "_ENV='prod' node ./build.js",
-    "start:dev": "concurrently --kill-others-on-fail -n webpack,server -c cyan,green \"pnpm build:dev\" \"pnpm dev\"",
-    "start:prod": "pnpm build:prod && pnpm prod",
-    "new-page": "node ./node_modules/lumfall/scripts/generate-page.js"
-  },
-  "dependencies": {
-    "lumfall": "^1.2.1"
-  },
-  "devDependencies": {
-    "concurrently": "^10.0.5",
-    "nodemon": "^3.1.14"
-  },
-  "packageManager": "pnpm@10.30.0",
-  "keywords": [
-    "lumfall",
-    "koa",
-    "vue",
-    "fullstack"
-  ],
-  "license": "ISC"
-}

package/templates/basic/server.js

@@ -1,26 +0,0 @@
-const { serviceStart } = require("lumfall");
-
-const app = serviceStart({
-  // 应用名：渲染页面模板 <title> 时使用
-  name: "lumfall-basic-project",
-
-  // 未命中任何路由时的 302 兜底目标。
-  // 注意：serviceStart 一旦传入 options 对象，就不再套用框架默认值，
-  // homePath 必须在这里显式声明，否则兜底重定向会退化为 "/"
-  homePath: "/view/home",
-
-  // 可选：配置强校验。传入 JSON Schema，合并后的配置不匹配会直接启动失败
-  // configSchema: require("./config/config.schema.js"),
-
-  // 可选：启动 / 停止 hook（beforeStart / beforeRouteLoad / afterRouteLoad /
-  // afterStart / onError / beforeStop / afterStop），启动期 hook 必须同步
-  // lifecycle: {},
-
-  // 可选：插件（数据库、缓存等先于业务中间件/路由初始化的能力）
-  // plugins: [],
-
-  // 可选：请求级观测 hook（traceId / onRequestStart / onRequestEnd / onRequestError）
-  // monitoring: {},
-});
-
-module.exports = app;

package/templates/document/README.md

@@ -1,145 +0,0 @@
-# lumfall-document
-
-基于 [lumfall](https://www.npmjs.com/package/lumfall) 的技术文档站模板，
-对标 VitePress 的使用体验：顶部导航、侧边栏、页面目录（TOC）、
-站内搜索（Ctrl/Cmd+K）、代码高亮与复制、亮 / 暗主题、上一篇/下一篇、移动端适配。
-
-模板本身是自举的：**内置内容就是 lumfall 框架的技术文档**，换掉内容即可为
-任何项目搭文档站。文档是纯前端渲染的 SPA，内容由构建期打进产物，无需后端 API。
-
-## 快速开始
-
-```sh
-pnpm install
-pnpm start:dev                # 本地开发：webpack dev server + 服务
-# 打开 http://localhost:3000/view/docs
-
-pnpm start:prod               # 生产构建 + 启动（Koa 服务）
-```
-
-环境变量 `_ENV`（local / beta / prod）与构建部署细节同 lumfall 基础工程，
-见[构建与部署文档](docs/guide/deployment.md)。
-
-## 部署到 Vercel（静态托管）
-
-文档站是纯前端 SPA：markdown 在构建期全部打进 bundle，运行时不调用任何接口，
-因此**不需要 Node 进程**，可以直接以静态站点部署到 Vercel / Netlify / Nginx。
-
-```sh
-pnpm build:static             # 产出 dist-static/（index.html + app.html + vercel.json + dist/prod/）
-
-cd dist-static && vercel --prod   # CLI 部署
-```
-
-或使用 Git 集成：Vercel 项目设置 **Build Command** = `pnpm build:static`，
-**Output Directory** = `dist-static`，Framework Preset 选 Other。
-
-`dist-static/` 的组成：
-
-| 文件 | 作用 |
-| --- | --- |
-| `app.html` | 应用外壳（由框架页面模板转换，`window.__LUMFALL__` 替换为静态值） |
-| `index.html` | `/` 的重定向页（跳到 `/view/docs`，替代 Koa 的 302 兜底） |
-| `vercel.json` | SPA rewrite：`/view/docs/*` → `app.html`；`dist/prod/*` 长缓存头 |
-| `dist/prod/...` | 构建产物（保持 `/dist/prod/` 绝对路径可解析） |
-
-其他平台的等价配置：把 `/view/docs` 与 `/view/docs/:path*` rewrite 到
-`app.html`（Netlify 的 `_redirects`、Nginx 的 `try_files` 即可），`/` 指向
-`index.html`。深链接刷新、站内路由、客户端 404 页全部由前端自行处理。
-
-::: warning 静态模式的能力边界
-静态部署只有文档站页面：框架自带的 `/view/health`、`/view/dashboard`、
-`/health/*`、`/api/*` 都不存在；如果往文档站里加 curl 调接口的功能，
-需要回到 Koa 部署（或为接口单独部署服务）。
-:::
-
-## 目录结构
-
-```text
-lumfall-document/
-├── server.js                  # 服务端入口（homePath 指向 /view/docs）
-├── build.js                   # 前端构建入口
-├── scripts/build-static.js    # 静态站点构建（pnpm build:static → dist-static/）
-├── config/                    # 环境配置（同基础工程）
-├── docs/                      # ★ 文档内容：全部 markdown，目录结构随意
-│   ├── guide/
-│   ├── core/
-│   ├── dsl/                   # Dashboard DSL 章节（Model+Project、schema 模块、接口契约）
-│   ├── frontend/
-│   ├── advanced/
-│   └── reference/
-└── app/
-    ├── webpack.config.js      # 额外声明了 .md 的 asset/source 规则
-    └── pages/
-        └── docs/              # 文档站页面（单页 + 站内路由）
-            ├── entry.docs.js  # 页面入口：注册 /view/docs 两条路由
-            ├── docs-config.js # ★ 站点配置：导航、侧栏、首页 hero、页脚
-            ├── content.js     # 内容加载器：require.context 扫 docs/ 下所有 .md
-            ├── markdown/      # markdown-it 渲染器（锚点/TOC/代码块/提示块/链接）
-            ├── search.js      # 站内搜索索引
-            ├── theme.js       # 亮暗主题
-            ├── components/    # navbar / sidebar / toc / search / layout
-            ├── views/         # 首页（hero）与文档页
-            └── styles/        # 设计变量与排版样式（CSS 变量驱动双主题）
-```
-
-## 用它搭自己的文档站
-
-三步：
-
-1. **改内容**：把 `docs/` 下的 markdown 换成自己的（目录层级随意，
-   两级以内体验最佳）。文档里可以互相引用，支持相对链接：
-   ```markdown
-   [配置](./config.md)          → 同目录
-   [路由](../core/router-schema.md) → 上级目录
-   [某节](./config.md#读取配置)  → 带锚点
-   ```
-2. **改配置**：`app/pages/docs/docs-config.js` 是唯一需要动的配置文件——
-   站点名、导航、侧栏分组、首页 hero、页脚。侧栏条目的 `path` 对应
-   `docs/` 下的文件路径（`/view/docs/<path>` ↔ `docs/<path>.md`）
-3. **可选**：改主题色（`app/pages/docs/styles/vars.less` 的 `--doc-brand`
-   等变量）、换 logo（`app/pages/docs/assets/docs-logo.svg`）
-
-## 功能清单
-
-| 功能 | 说明 |
-| --- | --- |
-| 首页 hero | 大标题 + 标语 + 按钮 + 特性卡片（配置驱动） |
-| 侧边栏 | 分组导航，当前页高亮，移动端抽屉 |
-| 页面目录 | 正文右侧 TOC，滚动联动高亮（<1280px 隐藏） |
-| 站内搜索 | `Ctrl/Cmd + K` 或 `/` 唤起；标题 / 小节 / 正文加权匹配，关键词高亮摘要，键盘导航 |
-| 代码块 | highlight.js 按需注册语言、语言标签、一键复制、亮暗配色 |
-| markdown 扩展 | `::: tip / info / warning / danger <可选标题>` 提示块、标题锚点（悬停显示 #）、外链新窗口 |
-| 主题 | 亮 / 暗（右上角切换），首次进站跟随系统，localStorage 记忆 |
-| 上一篇/下一篇 | 按侧边栏顺序自动生成 |
-| 路由 | `/view/docs` 首页，`/view/docs/<path>` 文档页，未知路径显示 404 引导 |
-| SEO 基础 | 每页动态 `document.title`；如需完整 SEO 需要额外的预渲染方案 |
-
-## 写作约定
-
-- 每篇文档以 `# 一级标题` 开头（渲染为页面标题），章节用 `##` / `###`
-  （自动进入右侧 TOC 与搜索索引）
-- 代码块标注语言（`js` / `vue` / `bash` / `json`…）才会高亮
-- 小节标题会被 slug 化为锚点 id（中文保留原文字符），可直接 `#锚点` 引用
-- 不支持的内容：数学公式、mermaid 图（markdown-it 未接插件，需要时可在
-  `app/pages/docs/markdown/index.js` 自行扩展）
-
-## 搜索原理
-
-构建时全部 markdown 以文本形式打进 bundle（`asset/source`），
-搜索在浏览器内存里做索引（标题 / 小节标题 / 正文三级加权，代码块不参与）。
-文档量在几百页以内体验良好；更大规模时建议接后端搜索或引入 lunr/minisearch。
-
-## 常见问题
-
-- **改了 docs/ 下的 md 没生效**：dev 模式需要重新触发编译（保存任意被引用的
-  文件）；生产模式需要重新 `pnpm build:prod`
-- **侧栏点进去 404**：`docs-config.js` 里的 path 与 `docs/` 实际文件不一致
-- **想改页面挂载路径（/view/docs）**：改 `docs-config.js` 的 `DOCS_BASE`
-  与 `entry.docs.js` 里的两条路由 path，三处保持一致
-
-## 相关项目
-
-- `lumfall-basic-project/`：基础业务工程骨架（本模板的工程底座）
-- `lumfall-business/`：B 端全栈模板（Dashboard / schema 组件）
-- `lumfall/`：框架本体

package/templates/document/app/extend/README.md

@@ -1,6 +0,0 @@
-// 扩展点目录：每个文件导出 (app) => object，返回值直接挂到 app 上。
-// 例如注册业务健康探针（文档站默认没有外部依赖，无需探针）：
-//   module.exports = (app) => {
-//     app.health.register("database", async () => { /* ping */ });
-//     return {};
-//   };

package/templates/document/app/middleware/README.md

@@ -1,2 +0,0 @@
-// 可复用中间件目录：每个文件导出 (app) => (ctx, next) => {}，
-// 自动挂载到 app.middlewares.<目录名>.<文件名>（kebab/snake-case 自动转 camelCase）。

package/templates/document/app/middleware.js

@@ -1,2 +0,0 @@
-// 业务全局中间件注册入口。文档站是纯静态站点，默认不需要额外中间件。
-module.exports = (app) => {};

package/templates/document/app/pages/docs/assets/docs-logo.svg

@@ -1,5 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
-  <rect x="2" y="2" width="28" height="28" rx="7" fill="#165dff"/>
-  <path d="M10 9v11a3 3 0 0 0 3 3h9v-2h-9a1 1 0 0 1-1-1V9h-2z" fill="#fff"/>
-  <path d="M13 9h9a1 1 0 0 1 1 1v8h-8a2 2 0 0 0-2 2V9z" fill="#9fd4ff"/>
-</svg>