mvframe 1.0.4 → 1.0.6

package/scripts/scaffold-app.js

@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+/**
+ * 在目标工程生成 MVFrame 推荐目录与雏形文件（views / component / api / pinia / router / config / assets）。
+ *
+ * 用法：
+ *   node path/to/mvframe/scripts/scaffold-app.js [项目根] [--force]
+ *   yarn exec mvframe-init-app
+ *
+ * 环境变量：MVFRAME_SCAFFOLD_TARGET=/path/to/project
+ *
+ * 选项：--no-package-json  不读不写 package.json（仅生成源码与 Vite 配置）
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+const FORCE = process.argv.includes("--force");
+const NO_PKG = process.argv.includes("--no-package-json");
+const argPath = process.argv.find(
+  (a, i) => i >= 2 && a !== "--force" && !a.startsWith("--"),
+);
+const target = path.resolve(
+  process.env.MVFRAME_SCAFFOLD_TARGET || argPath || process.cwd(),
+);
+
+function write(rel, content) {
+  const fp = path.join(target, rel);
+  fs.mkdirSync(path.dirname(fp), { recursive: true });
+  if (fs.existsSync(fp) && !FORCE) {
+    console.warn("[mvframe-init] 已存在，跳过（使用 --force 覆盖）:", rel);
+    return;
+  }
+  fs.writeFileSync(fp, content, "utf8");
+  console.log("[mvframe-init] 写入", rel);
+}
+
+/** 与 main.js / vite.config 模板一致；版本号与 mvframe 本仓库对齐思路，可随发布调整 */
+const SCAFFOLD_DEPENDENCIES = {
+  vue: "^3.5.0",
+  "vue-router": "^4.6.0",
+  pinia: "^3.0.0",
+  mvframe: "^1.0.0",
+  "element-plus": "^2.13.0",
+};
+
+const SCAFFOLD_DEV_DEPENDENCIES = {
+  vite: "^6.0.0",
+  "@vitejs/plugin-vue": "^5.2.0",
+  "sass-embedded": "^1.97.0",
+  "unplugin-auto-import": "^0.18.2",
+};
+
+/**
+ * 合并 package.json：保留原有字段与其它依赖；仅补足脚手架所需包。
+ * 同名依赖以目标项目已有版本为准（{ ...建议, ...已有 }）。
+ */
+function mergePackageJson(projectRoot) {
+  const pkgPath = path.join(projectRoot, "package.json");
+  let pkg;
+
+  if (fs.existsSync(pkgPath)) {
+    try {
+      pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    } catch (e) {
+      console.warn("[mvframe-init] package.json 解析失败，跳过合并:", e.message);
+      return;
+    }
+  } else {
+    pkg = {
+      name: path.basename(projectRoot).replace(/[^a-z0-9-]/gi, "-").toLowerCase() || "mvframe-app",
+      version: "0.1.0",
+      private: true,
+      type: "module",
+      scripts: {
+        dev: "vite",
+        build: "vite build",
+        preview: "vite preview",
+      },
+    };
+    console.log("[mvframe-init] 新建 package.json");
+  }
+
+  pkg.dependencies = {
+    ...SCAFFOLD_DEPENDENCIES,
+    ...(pkg.dependencies && typeof pkg.dependencies === "object" ? pkg.dependencies : {}),
+  };
+  pkg.devDependencies = {
+    ...SCAFFOLD_DEV_DEPENDENCIES,
+    ...(pkg.devDependencies && typeof pkg.devDependencies === "object"
+      ? pkg.devDependencies
+      : {}),
+  };
+
+  fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, "utf8");
+  console.log("[mvframe-init] 已合并 package.json 的 dependencies / devDependencies（已有版本优先）");
+}
+
+function main() {
+  if (!fs.existsSync(target)) {
+    console.error("[mvframe-init] 目录不存在:", target);
+    process.exit(1);
+  }
+
+  const dirs = [
+    "src/views/Home",
+    "src/views/Admin",
+    "src/component",
+    "src/assets/img",
+    "src/assets/style",
+    "src/api",
+    "src/router",
+    "src/pinia/chip",
+    "src/config",
+    "src/composition",
+  ];
+  for (const d of dirs) {
+    fs.mkdirSync(path.join(target, d), { recursive: true });
+  }
+
+  write(
+    "src/main.js",
+    `import { createApp } from "vue";
+import ElementPlus from "element-plus";
+import "element-plus/dist/index.css";
+import App from "./App.vue";
+import mvframe from "mvframe";
+import routes from "./router/index.js";
+import appConfig from "./config/index.js";
+import "./assets/style/index.scss";
+
+const app = createApp(App);
+app.use(ElementPlus);
+app.use(mvframe, {
+  vueRouter: {
+    routes,
+  },
+  pinia: {
+    useTab: true,
+    storeChips: import.meta.glob("./pinia/chip/*.js", { eager: true }),
+  },
+  config: appConfig,
+});
+app.mount("#app");
+`,
+  );
+
+  write(
+    "src/App.vue",
+    `<template>
+  <Frame class="App" :menu="menu" :page="{}">
+    <template #logo>
+      <span class="logo-placeholder">Logo</span>
+    </template>
+    <template #logomini>
+      <span class="logo-mini">L</span>
+    </template>
+  </Frame>
+</template>
+<script setup>
+import routes from "./router/index.js";
+
+defineOptions({
+  name: "App",
+  inheritAttrs: false,
+});
+
+const menu = {
+  iconClass: "imicon",
+  routes,
+};
+</script>
+<style lang="scss" scoped>
+.logo-placeholder {
+  display: inline-block;
+  min-width: 7.5rem;
+  padding: 0.25rem 0.5rem;
+  border-radius: 0.25rem;
+  background: var(--color-primary, #16b1ff);
+  color: #fff;
+  font-size: 0.875rem;
+}
+.logo-mini {
+  display: inline-flex;
+  width: 1.875rem;
+  height: 1.875rem;
+  align-items: center;
+  justify-content: center;
+  border-radius: 0.25rem;
+  background: var(--color-green, #20c997);
+  color: #fff;
+  font-size: 0.75rem;
+}
+</style>
+`,
+  );
+
+  write(
+    "src/router/baseRouter.js",
+    `/**
+ * 基础路由：登录页、公开页、与后台权限无关的入口。
+ * 权限接口返回后若要合并，可在本文件导出函数内拼接，或与 adminRouter 在 index 中组合。
+ */
+export default [
+  {
+    path: "/",
+    name: "Home_Home",
+    component: () => import("@/views/Home/Home.vue"),
+    meta: {
+      title: "Home",
+    },
+  },
+];
+`,
+  );
+
+  write(
+    "src/router/adminRouter.js",
+    `/**
+ * 后台 / 业务路由：可按接口权限过滤后追加，或整段替换。
+ * meta.admin 等字段可与 mvframe vueRouter.useAdmin / adminPermission 配合。
+ */
+export default [
+  {
+    path: "/admin",
+    name: "Admin_Dashboard",
+    component: () => import("@/views/Admin/Dashboard.vue"),
+    meta: {
+      title: "Dashboard",
+      icon: "im-setting",
+      // admin: true,
+    },
+  },
+];
+`,
+  );
+
+  write(
+    "src/router/index.js",
+    `import baseRouter from "./baseRouter.js";
+import adminRouter from "./adminRouter.js";
+
+/** 交给 mvframe 的 vueRouter.routes（菜单与注册同源，无需拆两份维护） */
+export default [...baseRouter, ...adminRouter];
+`,
+  );
+
+  write(
+    "src/config/index.js",
+    `/**
+ * 与 mvframe 内置 config 合并 → globalThis.$config
+ * @type {Record<string, unknown>}
+ */
+export default {
+  iconfont: {
+    // url: "//at.alicdn.com/t/c/your_font.js",
+    // prefix: "ant",
+  },
+  table: {
+    summaryMetric: null,
+  },
+};
+`,
+  );
+
+  write(
+    "src/pinia/chip/app.js",
+    `/** 业务 Pinia chip：路径须为 pinia/chip/*.js，export default { state, actions } */
+const state = () => ({
+  // demo: null,
+});
+
+const actions = {
+  saveData(key, value) {
+    this[key] = value;
+  },
+};
+
+export default {
+  state,
+  actions,
+};
+`,
+  );
+
+  write(
+    "src/api/index.js",
+    `/**
+ * 接口聚合：按需拆分 chip 并在业务中 import
+ * 例：export * from "./chip/user.js";
+ */
+export {};
+`,
+  );
+
+  write(
+    "src/assets/style/index.scss",
+    `/* 项目全局样式入口（已在 main.js 引入） */
+
+/* MVFrame 工具类与变量：按安装方式选一种
+ * - monorepo / 源码依赖：*/
+/* @import "mvframe/src/style/index.scss"; */
+
+/* - 发布包全量样式：*/
+/* @import "mvframe/style"; */
+
+body {
+  margin: 0;
+}
+`,
+  );
+
+  write(
+    "src/views/Admin/Dashboard.vue",
+    `<template>
+  <Page title="Dashboard" subtitle="后台路由示例（adminRouter）">
+    <p>在 <code>src/router/adminRouter.js</code> 扩展；与 <code>baseRouter.js</code> 在 <code>index.js</code> 合并。</p>
+  </Page>
+</template>
+<script setup>
+defineOptions({
+  name: "AdminDashboard",
+  inheritAttrs: false,
+});
+</script>
+<style lang="scss" scoped>
+code {
+  font-size: 0.875rem;
+}
+</style>
+`,
+  );
+
+  write(
+    "src/views/Home/Home.vue",
+    `<template>
+  <Page title="Home" subtitle="MVFrame 雏形页，可从此扩展 views 模块">
+    <p>公开路由见 <code>src/router/baseRouter.js</code>；后台见 <code>adminRouter.js</code>，合并于 <code>index.js</code>。</p>
+  </Page>
+</template>
+<script setup>
+defineOptions({
+  name: "HomeHome",
+  inheritAttrs: false,
+});
+</script>
+<style lang="scss" scoped>
+code {
+  font-size: 0.875rem;
+}
+</style>
+`,
+  );
+
+  write("src/component/.gitkeep", "");
+  write("src/assets/img/.gitkeep", "");
+  write("src/composition/.gitkeep", "");
+
+  const idxHtml = path.join(target, "index.html");
+  if (!fs.existsSync(idxHtml) || FORCE) {
+    write(
+      "index.html",
+      `<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>
+`,
+    );
+  }
+
+  const viteConfig = path.join(target, "vite.config.js");
+  if (!fs.existsSync(viteConfig) || FORCE) {
+    write(
+      "vite.config.js",
+      `import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import path from "path";
+import { fileURLToPath } from "url";
+import AutoImport from "unplugin-auto-import/vite";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    AutoImport({
+      include: [/\\.vue$/, /\\.vue\\?vue/, /\\.js$/],
+      imports: ["vue", "vue-router"],
+      vueTemplate: true,
+      dts: true,
+    }),
+  ],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "src"),
+      "@cps": path.resolve(__dirname, "src/composition"),
+    },
+  },
+  server: {
+    port: 5173,
+  },
+});
+`,
+    );
+  }
+
+  write(
+    "MVFRAME-SCAFFOLD.md",
+    `# MVFrame 雏形已生成
+
+## 依赖
+
+初始化脚本会**合并**（不整文件覆盖）\`package.json\` 的 \`dependencies\` / \`devDependencies\`：**已声明的包保留你的版本号**，仅补上缺失项。然后执行：
+
+\`\`\`bash
+yarn install
+\`\`\`
+
+若需跳过对 \`package.json\` 的修改：\`node scripts/scaffold-app.js --no-package-json\`。
+
+自动生成的 \`vite.config.js\` 已包含 \`unplugin-auto-import\`；\`dts: true\` 时类型默认写在项目根 \`auto-imports.d.ts\`。
+
+## 样式
+
+在 \`src/assets/style/index.scss\` 中取消注释并指向实际 mvframe 样式路径（源码或 dist）。
+
+## 目录约定
+
+| 路径 | 用途 |
+|------|------|
+| \`src/views\` | 主要页面（模块大驼峰 + \`Home.vue\`，见 mvframe views 规范） |
+| \`src/component\` | 项目级公共组件（与 mvframe 全局 \`Mvc*\` 区分） |
+| \`src/api\` | 接口 |
+| \`src/assets/style\` | 样式入口，main.js 已 import |
+| \`src/assets/img\` | 静态图 |
+| \`src/router/baseRouter.js\` | 基础路由（公开页等） |
+| \`src/router/adminRouter.js\` | 后台 / 业务路由（可按权限过滤后合并） |
+| \`src/router/index.js\` | 合并导出 → \`vueRouter.routes\`（与 Frame \`menu.routes\` 同源） |
+| \`src/pinia/chip/*.js\` | 业务 store → \`storeChips: import.meta.glob(...)\` |
+| \`src/config/index.js\` | 合并进 \`globalThis.$config\` |
+| \`src/composition\` | 可选，与 Vite 别名 \`@cps\` 对应 |
+
+## Cursor Skill（可选）
+
+\`\`\`bash
+yarn exec mvframe-install-cursor-skill
+\`\`\`
+`,
+  );
+
+  if (!NO_PKG) {
+    mergePackageJson(target);
+  }
+
+  console.log(
+    "[mvframe-init] 完成。请阅读 MVFRAME-SCAFFOLD.md 并在项目根执行 yarn install（或 npm install）。",
+  );
+}
+
+main();