create-lumfall 1.0.0 → 1.1.1

package/templates/document/app/pages/docs/components/doc-layout.vue

@@ -1,144 +0,0 @@
-<template>
-  <div class="doc-shell">
-    <DocNavbar
-      :show-sidebar-toggle="sidebar"
-      @toggle-sidebar="drawerOpen = !drawerOpen"
-      @open-search="searchOpen = true"
-    />
-
-    <div class="doc-body" @click="handleBodyClick">
-      <DocSidebar v-if="sidebar" class="doc-desktop-sidebar" />
-
-      <!-- 移动端抽屉侧栏 -->
-      <Transition name="doc-fade">
-        <div v-if="sidebar && drawerOpen" class="doc-drawer-mask" @click.self="drawerOpen = false">
-          <DocSidebar class="doc-drawer-sidebar" @navigate="drawerOpen = false" />
-        </div>
-      </Transition>
-
-      <main class="doc-main">
-        <slot />
-      </main>
-    </div>
-
-    <DocSearch v-model="searchOpen" />
-  </div>
-</template>
-
-<script setup>
-import { onBeforeUnmount, onMounted, ref, watch } from "vue";
-import { useRoute, useRouter } from "vue-router";
-import DocNavbar from "./doc-navbar.vue";
-import DocSidebar from "./doc-sidebar.vue";
-import DocSearch from "./doc-search.vue";
-
-defineProps({
-  // 是否显示侧栏（首页不显示）
-  sidebar: { type: Boolean, default: true },
-});
-
-const route = useRoute();
-const router = useRouter();
-const drawerOpen = ref(false);
-const searchOpen = ref(false);
-
-// 路由切换时收起移动端抽屉
-watch(
-  () => route.fullPath,
-  () => {
-    drawerOpen.value = false;
-  }
-);
-
-// ---- 全局点击处理：复制代码 / 站内路由 / 锚点平滑滚动 ----
-const copyText = (text) => {
-  if (navigator.clipboard && window.isSecureContext) {
-    navigator.clipboard.writeText(text);
-    return;
-  }
-  // 非安全上下文（http 部署）回退方案
-  const textarea = document.createElement("textarea");
-  textarea.value = text;
-  textarea.style.position = "fixed";
-  textarea.style.opacity = "0";
-  document.body.appendChild(textarea);
-  textarea.select();
-  try {
-    document.execCommand("copy");
-  } catch (err) {
-    // 忽略复制失败
-  }
-  document.body.removeChild(textarea);
-};
-
-const handleBodyClick = (e) => {
-  // 1. 代码块复制按钮
-  const copyBtn = e.target.closest(".doc-code-copy");
-  if (copyBtn) {
-    const block = copyBtn.closest(".doc-code-block");
-    const pre = block && block.querySelector("pre");
-    if (pre) {
-      copyText(pre.textContent || "");
-      copyBtn.textContent = "已复制";
-      setTimeout(() => {
-        copyBtn.textContent = "复制";
-      }, 1500);
-    }
-    return;
-  }
-
-  // 2. 站内文档链接走 SPA 路由，避免整页刷新
-  const link = e.target.closest("a");
-  if (!link) {
-    return;
-  }
-  const href = link.getAttribute("href") || "";
-
-  if (href.startsWith("/view/docs")) {
-    e.preventDefault();
-    router.push(href);
-    return;
-  }
-
-  // 3. 页内锚点：平滑滚动，滚动结束后再更新 URL。
-  //    注意：带 fragment 的 history.replaceState 会取消 Chrome 正在进行的
-  //    平滑滚动（无论先后调用），所以必须等 scrollend 之后再写 URL。
-  if (href.startsWith("#") && href.length > 1) {
-    const target = document.getElementById(decodeURIComponent(href.slice(1)));
-    if (target) {
-      e.preventDefault();
-      let urlUpdated = false;
-      const updateUrl = () => {
-        if (urlUpdated) return;
-        urlUpdated = true;
-        history.replaceState(null, "", href);
-      };
-      target.scrollIntoView({ behavior: "smooth" });
-      // 平滑滚动结束（scrollend 支持前用定时器兜底；目标已在视口内时不会滚动）
-      window.addEventListener("scrollend", updateUrl, { once: true });
-      setTimeout(updateUrl, 800);
-    }
-  }
-};
-
-// 全局快捷键：Ctrl/Cmd + K 或 / 唤起搜索（输入框内按 / 不触发）
-const onGlobalKeydown = (e) => {
-  const isCtrlK = (e.ctrlKey || e.metaKey) && e.key.toLowerCase() === "k";
-  const isSlash =
-    e.key === "/" &&
-    !["INPUT", "TEXTAREA"].includes(e.target.tagName) &&
-    !e.target.isContentEditable;
-  if (isCtrlK || isSlash) {
-    e.preventDefault();
-    searchOpen.value = true;
-  }
-};
-
-onMounted(() => {
-  window.addEventListener("keydown", onGlobalKeydown);
-});
-
-onBeforeUnmount(() => {
-  window.removeEventListener("keydown", onGlobalKeydown);
-});
-</script>

package/templates/document/app/pages/docs/components/doc-navbar.vue

@@ -1,103 +0,0 @@
-<template>
-  <header class="doc-navbar">
-    <div class="doc-navbar-left">
-      <button
-        v-if="showSidebarToggle"
-        class="doc-navbar-burger"
-        type="button"
-        aria-label="打开目录"
-        @click="$emit('toggle-sidebar')"
-      >
-        <icon-menu />
-      </button>
-
-      <router-link class="doc-navbar-brand" to="/view/docs">
-        <img class="doc-navbar-logo" :src="logo" alt="logo" />
-        <span class="doc-navbar-title">{{ site.title }}</span>
-      </router-link>
-
-      <nav class="doc-navbar-nav">
-        <template v-for="item in nav" :key="item.text">
-          <router-link
-            v-if="item.path"
-            :to="item.path"
-            class="doc-navbar-link"
-            :class="{ active: isActive(item) }"
-          >
-            {{ item.text }}
-          </router-link>
-          <a
-            v-else
-            :href="item.link"
-            target="_blank"
-            rel="noopener noreferrer"
-            class="doc-navbar-link"
-          >
-            {{ item.text }}
-          </a>
-        </template>
-      </nav>
-    </div>
-
-    <div class="doc-navbar-right">
-      <button class="doc-search-trigger" type="button" @click="$emit('open-search')">
-        <icon-search />
-        <span class="doc-search-trigger-text">搜索文档</span>
-        <kbd>Ctrl K</kbd>
-      </button>
-
-      <button
-        class="doc-icon-btn"
-        type="button"
-        :aria-label="isDark ? '切换到亮色' : '切换到暗色'"
-        @click="handleToggleTheme"
-      >
-        <icon-sun-fill v-if="isDark" />
-        <icon-moon-fill v-else />
-      </button>
-
-      <a
-        v-if="site.repo"
-        class="doc-icon-btn"
-        :href="site.repo"
-        target="_blank"
-        rel="noopener noreferrer"
-        aria-label="GitHub 仓库"
-      >
-        <icon-github />
-      </a>
-    </div>
-  </header>
-</template>
-
-<script setup>
-import { computed, ref } from "vue";
-import { useRoute } from "vue-router";
-import docsConfig from "../docs-config";
-import { toggleTheme } from "../theme";
-import logo from "../assets/docs-logo.svg";
-
-defineProps({
-  showSidebarToggle: { type: Boolean, default: false },
-});
-
-defineEmits(["toggle-sidebar", "open-search"]);
-
-const route = useRoute();
-const site = docsConfig.site;
-const nav = docsConfig.nav;
-const isDark = ref(document.body.getAttribute("arco-theme") === "dark");
-
-const handleToggleTheme = () => {
-  isDark.value = toggleTheme() === "dark";
-};
-
-// 导航高亮：按 path 的前三级（/view/docs/<section>）匹配当前路由
-const isActive = (item) => {
-  if (!item.path) {
-    return false;
-  }
-  const section = item.path.split("/").slice(0, 4).join("/");
-  return route.path === section || route.path.startsWith(`${section}/`);
-};
-</script>

package/templates/document/app/pages/docs/components/doc-search.vue

@@ -1,131 +0,0 @@
-<template>
-  <Teleport to="body">
-    <Transition name="doc-fade">
-      <div v-if="modelValue" class="doc-search-mask" @click.self="close">
-        <div class="doc-search-panel">
-          <div class="doc-search-input-row">
-            <icon-search class="doc-search-icon" />
-            <input
-              ref="inputRef"
-              v-model="keyword"
-              class="doc-search-input"
-              type="text"
-              placeholder="搜索文档，如：配置 / 路由 / 插件"
-              @keydown="onKeydown"
-            />
-            <kbd class="doc-search-kbd">ESC</kbd>
-          </div>
-
-          <div class="doc-search-results">
-            <template v-if="keyword.trim()">
-              <div v-if="!results.length" class="doc-search-empty">
-                没有找到与「{{ keyword }}」相关的内容
-              </div>
-              <a
-                v-for="(item, i) in results"
-                :key="`${item.docPath}-${item.anchor}-${i}`"
-                class="doc-search-item"
-                :class="{ active: i === activeIndex }"
-                @click="go(item)"
-                @mouseenter="activeIndex = i"
-              >
-                <div class="doc-search-item-title" v-html="item.titleHtml"></div>
-                <div v-if="item.heading" class="doc-search-item-heading">
-                  <icon-right /> {{ item.heading }}
-                </div>
-                <div
-                  v-if="item.snippet"
-                  class="doc-search-item-snippet"
-                  v-html="item.snippet"
-                ></div>
-              </a>
-            </template>
-            <div v-else class="doc-search-empty">
-              输入关键词开始搜索，支持标题与正文匹配
-            </div>
-          </div>
-
-          <div class="doc-search-footer">
-            <span><kbd>↑</kbd><kbd>↓</kbd> 选择</span>
-            <span><kbd>Enter</kbd> 打开</span>
-            <span><kbd>ESC</kbd> 关闭</span>
-          </div>
-        </div>
-      </div>
-    </Transition>
-  </Teleport>
-</template>
-
-<script setup>
-import { computed, nextTick, ref, watch } from "vue";
-import { useRouter } from "vue-router";
-import docsConfig from "../docs-config";
-import { searchDocs } from "../search";
-
-const props = defineProps({
-  modelValue: { type: Boolean, default: false },
-});
-const emit = defineEmits(["update:modelValue"]);
-
-const router = useRouter();
-const keyword = ref("");
-const activeIndex = ref(0);
-const inputRef = ref(null);
-
-const results = computed(() => {
-  const list = searchDocs(keyword.value, docsConfig);
-  if (activeIndex.value >= list.length) {
-    activeIndex.value = 0;
-  }
-  return list;
-});
-
-watch(
-  () => props.modelValue,
-  (open) => {
-    if (open) {
-      keyword.value = "";
-      activeIndex.value = 0;
-      nextTick(() => inputRef.value && inputRef.value.focus());
-    }
-  }
-);
-
-watch(keyword, () => {
-  activeIndex.value = 0;
-});
-
-const close = () => emit("update:modelValue", false);
-
-const go = (item) => {
-  close();
-  const path = `/view/docs/${item.docPath}`;
-  if (item.anchor) {
-    router.push({ path, hash: `#${item.anchor}` });
-  } else {
-    router.push(path);
-  }
-};
-
-const onKeydown = (e) => {
-  if (e.key === "Escape") {
-    close();
-  } else if (e.key === "ArrowDown") {
-    e.preventDefault();
-    activeIndex.value = (activeIndex.value + 1) % Math.max(results.value.length, 1);
-  } else if (e.key === "ArrowUp") {
-    e.preventDefault();
-    activeIndex.value =
-      (activeIndex.value - 1 + results.value.length) %
-      Math.max(results.value.length, 1);
-  } else if (e.key === "Enter") {
-    const item = results.value[activeIndex.value];
-    if (item) {
-      go(item);
-    }
-  }
-};
-
-// 暴露给全局快捷键：layout 或页面可通过 ref 调 open()（本模板用 v-model 控制即可）
-defineExpose({ close });
-</script>

package/templates/document/app/pages/docs/components/doc-sidebar.vue

@@ -1,29 +0,0 @@
-<template>
-  <aside class="doc-sidebar">
-    <div v-for="group in sidebar" :key="group.text" class="doc-sidebar-group">
-      <div class="doc-sidebar-group-title">{{ group.text }}</div>
-      <router-link
-        v-for="item in group.items"
-        :key="item.path"
-        :to="item.path"
-        class="doc-sidebar-link"
-        :class="{ active: isActive(item.path) }"
-        @click="$emit('navigate')"
-      >
-        {{ item.text }}
-      </router-link>
-    </div>
-  </aside>
-</template>
-
-<script setup>
-import { useRoute } from "vue-router";
-import docsConfig from "../docs-config";
-
-defineEmits(["navigate"]);
-
-const route = useRoute();
-const sidebar = docsConfig.sidebar;
-
-const isActive = (path) => route.path === path || route.path === `${path}/`;
-</script>

package/templates/document/app/pages/docs/components/doc-toc.vue

@@ -1,21 +0,0 @@
-<template>
-  <div v-if="items.length" class="doc-toc">
-    <div class="doc-toc-title">页面内容</div>
-    <a
-      v-for="item in items"
-      :key="item.id"
-      :href="`#${item.id}`"
-      class="doc-toc-link"
-      :class="[`level-${item.level}`, { active: item.id === activeId }]"
-    >
-      {{ item.text }}
-    </a>
-  </div>
-</template>
-
-<script setup>
-defineProps({
-  items: { type: Array, default: () => [] },
-  activeId: { type: String, default: "" },
-});
-</script>

package/templates/document/app/pages/docs/content.js

@@ -1,28 +0,0 @@
-// markdown 文档内容加载器。
-// 约定：文档放在项目根目录 docs/ 下（相对本文件 ../../../docs），
-// 构建时全部按原始文本打进产物，页面按路径读取并渲染。
-// 要调整内容目录位置时，只需要改 require.context 的第一个参数。
-const context = require.context("../../../docs", true, /\.md$/);
-
-const moduleMap = {};
-
-context.keys().forEach((key) => {
-  // key 形如 "./guide/introduction.md" → "guide/introduction"
-  const docPath = key.replace(/^\.\//, "").replace(/\.md$/, "");
-  const mod = context(key);
-  moduleMap[docPath] = typeof mod === "string" ? mod : mod.default ?? mod;
-});
-
-/**
- * 按 docs/ 相对路径取 markdown 原文
- * @param {string} docPath 例如 "guide/introduction"
- * @returns {string|undefined}
- */
-export function getDocSource(docPath) {
-  return moduleMap[docPath];
-}
-
-/** 全部文档：{ "guide/introduction": "# ...", ... } */
-export function getAllDocs() {
-  return moduleMap;
-}

package/templates/document/app/pages/docs/docs-config.js

@@ -1,154 +0,0 @@
-/**
- * 文档站配置 —— 使用本模板时主要改这个文件。
- *
- * 换成自己的站点只需三步：
- *   1. 改本文件的 site / nav / sidebar / hero / footer
- *   2. 把 docs/ 目录下的 markdown 换成自己的内容（目录结构随意，两层以内最佳）
- *   3. 想改页面挂载路径（/view/docs）时，改 DOCS_BASE 并同步 entry.docs.js 里的路由
- */
-
-// 站内文档的 URL 前缀 = /view/<页面目录名>
-const DOCS_BASE = "/view/docs";
-
-const doc = (path) => `${DOCS_BASE}/${path}`;
-
-export default {
-  // 站点信息
-  site: {
-    title: "Lumfall",
-    description: "Lumfall 全栈框架开发文档",
-    // 右上角仓库链接，不需要就置空
-    repo: "https://github.com/ikun-Lg/lumfall",
-  },
-
-  // 顶部导航：path 为站内路由（高亮按第一级 section 匹配），link 为外链
-  nav: [
-    { text: "指南", path: doc("guide/introduction") },
-    { text: "核心概念", path: doc("core/app-instance") },
-    { text: "DSL", path: doc("dsl/overview") },
-    { text: "前端", path: doc("frontend/page") },
-    { text: "进阶", path: doc("advanced/security") },
-    { text: "参考", path: doc("reference/faq") },
-    { text: "GitHub", link: "https://github.com/ikun-Lg/lumfall" },
-  ],
-
-  // 侧边栏分组。items 的 path 必须对应 docs/ 下真实存在的 markdown 文件
-  // （例如 doc("guide/introduction") 对应 docs/guide/introduction.md）
-  sidebar: [
-    {
-      text: "指南",
-      items: [
-        { text: "简介", path: doc("guide/introduction") },
-        { text: "快速开始", path: doc("guide/getting-started") },
-        { text: "目录结构与挂载点", path: doc("guide/structure") },
-        { text: "配置", path: doc("guide/config") },
-        { text: "构建与部署", path: doc("guide/deployment") },
-      ],
-    },
-    {
-      text: "核心概念",
-      items: [
-        { text: "app 对象与启动流程", path: doc("core/app-instance") },
-        { text: "Controller 与 Service", path: doc("core/controller-service") },
-        { text: "路由与参数校验", path: doc("core/router-schema") },
-        { text: "中间件", path: doc("core/middleware") },
-        { text: "生命周期", path: doc("core/lifecycle") },
-        { text: "插件", path: doc("core/plugins") },
-      ],
-    },
-    {
-      text: "DSL",
-      items: [
-        { text: "DSL 总览", path: doc("dsl/overview") },
-        { text: "Model 与 Project", path: doc("dsl/model-project") },
-        { text: "菜单项 DSL", path: doc("dsl/menu") },
-        { text: "schema 模块 DSL", path: doc("dsl/schema") },
-        { text: "按钮与动态表单", path: doc("dsl/schema-actions") },
-        { text: "接口契约", path: doc("dsl/api-contract") },
-        { text: "扩展 DSL", path: doc("dsl/extend") },
-        { text: "完整模板与注意事项", path: doc("dsl/reference") },
-      ],
-    },
-    {
-      text: "前端",
-      items: [
-        { text: "页面系统", path: doc("frontend/page") },
-        { text: "前端构建", path: doc("frontend/build") },
-        { text: "内置组件", path: doc("frontend/widgets") },
-        { text: "请求工具 curl", path: doc("frontend/curl") },
-      ],
-    },
-    {
-      text: "进阶",
-      items: [
-        { text: "安全策略", path: doc("advanced/security") },
-        { text: "健康检查", path: doc("advanced/health") },
-        { text: "请求观测 monitoring", path: doc("advanced/monitoring") },
-        { text: "Dashboard 与 Model 配置", path: doc("advanced/dashboard") },
-      ],
-    },
-    {
-      text: "参考",
-      items: [
-        { text: "常见错误自查", path: doc("reference/faq") },
-        { text: "命令与环境速查", path: doc("reference/commands") },
-      ],
-    },
-  ],
-
-  // 首页 hero
-  hero: {
-    name: "Lumfall",
-    tagline: "Koa + Vue 全栈框架，目录即约定，开箱即用",
-    text: "目录自动加载、四层配置合并、声明式 Dashboard DSL、页面与路由构建、安全策略、健康检查——写配置和业务代码，而不是搭工程。",
-    actions: [
-      { text: "快速开始", path: doc("guide/getting-started"), theme: "brand" },
-      { text: "DSL 设计", path: doc("dsl/overview"), theme: "brand-outline" },
-      { text: "GitHub", link: "https://github.com/ikun-Lg/lumfall" },
-    ],
-    features: [
-      {
-        icon: "📐",
-        title: "声明式 Dashboard DSL",
-        details:
-          "Model + Project 两层 DSL 声明管理台；一份字段 schema 驱动搜索栏、表格、表单、详情四个视图，写配置不改代码。",
-      },
-      {
-        icon: "📁",
-        title: "目录即约定",
-        details:
-          "controller / service / router / middleware 按目录自动加载并挂载到 app，新建文件即生效，无需手动注册。",
-      },
-      {
-        icon: "⚙️",
-        title: "四层配置合并",
-        details:
-          "框架与业务的 config 按 _ENV 分层浅合并，支持 JSON Schema 强校验，环境切换只改一个变量。",
-      },
-      {
-        icon: "🧩",
-        title: "页面系统",
-        details:
-          "Vue 3 页面按 entry.<name>.js 自动发现，Webpack 5 多页构建，/view/<name> 直接访问，支持 HMR 热更新。",
-      },
-      {
-        icon: "🛡️",
-        title: "内置安全策略",
-        details:
-          "接口签名校验与 project_key 校验开箱可用，参数校验基于 JSON Schema（Ajv），错误码统一。",
-      },
-      {
-        icon: "💚",
-        title: "健康检查与观测",
-        details:
-          "/health/live 与 /health/ready 内置探针机制；monitoring 提供请求级 trace 观测钩子；插件与生命周期覆盖启动退出。",
-      },
-    ],
-  },
-
-  // 首页与文档页底部
-  footer: {
-    text: "基于 lumfall 构建的文档站模板",
-    // copyright: "© 2026 Your Name",
-  },
-};

package/templates/document/app/pages/docs/docs.vue

@@ -1,24 +0,0 @@
-<template>
-  <a-config-provider :locale="zhCN">
-    <router-view />
-  </a-config-provider>
-</template>
-
-<script setup>
-import { onMounted } from "vue";
-import zhCN from "@arco-design/web-vue/es/locale/lang/zh-cn";
-import favicon from "./assets/docs-logo.svg";
-import "./styles/vars.less";
-import "./styles/docs.less";
-
-onMounted(() => {
-  // 框架通用模板没有 favicon 位，这里在运行时注入
-  if (!document.querySelector('link[rel="icon"]')) {
-    const link = document.createElement("link");
-    link.rel = "icon";
-    link.type = "image/svg+xml";
-    link.href = favicon;
-    document.head.appendChild(link);
-  }
-});
-</script>

package/templates/document/app/pages/docs/entry.docs.js

@@ -1,26 +0,0 @@
-import boot from "$lumfallBoot";
-import Docs from "./docs.vue";
-import { initTheme } from "./theme";
-
-// 尽早应用主题（localStorage / 系统偏好），避免首屏闪白
-initTheme();
-
-// 文档站是单个页面（app/pages/docs），站内路由：
-//   /view/docs            首页（hero + 特性卡片）
-//   /view/docs/<path>     文档页（path 对应 docs/<path>.md）
-// 页面目录名决定挂载路径（本页是 docs）；要改名时同步调整 docs-config.js 里的
-// DOCS_BASE 与上面两个路由 path。
-boot(Docs, {
-  routes: [
-    {
-      path: "/view/docs",
-      name: "doc-home",
-      component: () => import("./views/doc-home.vue"),
-    },
-    {
-      path: "/view/docs/:path(.*)",
-      name: "doc-page",
-      component: () => import("./views/doc-page.vue"),
-    },
-  ],
-});