create-swdg-frontend 0.1.6 → 0.2.0

package/template/src/data/onboardingSlides.ts

@@ -0,0 +1,208 @@
+export type SlideBlock =
+  | { type: 'p'; text: string }
+  | { type: 'ul'; items: string[] }
+  | { type: 'code'; text: string }
+  | { type: 'table'; headers: string[]; rows: string[][] }
+  | { type: 'links'; items: { label: string; to: string }[] };
+
+export interface OnboardingSlide {
+  id: string;
+  title: string;
+  tagline?: string;
+  blocks: SlideBlock[];
+}
+
+export const onboardingSlides: OnboardingSlide[] = [
+  {
+    id: 'welcome',
+    title: 'SWDG 前端模板',
+    tagline: 'Vue 3 · TypeScript · Vite · 约定式路由',
+    blocks: [
+      {
+        type: 'p',
+        text: '面向团队的标准前端壳：业务在 src/views 开发，示例与文档内置在开发模式，生产构建自动剔除演示路由。',
+      },
+      {
+        type: 'ul',
+        items: [
+          '直接 clone 本仓库，或在团队内迭代模板',
+          'pnpm create swdg my-app 脚手架生成独立项目',
+          '左右方向键 / 按钮翻页浏览本指南',
+        ],
+      },
+      {
+        type: 'links',
+        items: [{ label: '全屏幻灯片模式 →', to: '/examples/guide' }],
+      },
+    ],
+  },
+  {
+    id: 'quickstart',
+    title: '快速开始',
+    tagline: '第一次跑起来',
+    blocks: [
+      {
+        type: 'code',
+        text: 'pnpm install\ncp .env.example .env\npnpm dev',
+      },
+      {
+        type: 'ul',
+        items: [
+          '需要 Node.js 22+，推荐 pnpm 9+',
+          '默认 http://localhost:3000 ，Hash 路由 /#/',
+          '修改 .env 后必须重启 pnpm dev',
+        ],
+      },
+    ],
+  },
+  {
+    id: 'env',
+    title: '环境变量',
+    tagline: '.env 配置说明',
+    blocks: [
+      {
+        type: 'table',
+        headers: ['变量', '说明'],
+        rows: [
+          ['VITE_DEMO_PROXY_TARGET', '开发代理 /demo 的后端地址'],
+          ['VITE_FEATURE_GIS', 'true 时启用 Cesium 入口与示例'],
+          ['VITE_CESIUM_ION_ACCESS_TOKEN', '可选，默认 OSM 底图可不填'],
+        ],
+      },
+      {
+        type: 'p',
+        text: '看不到 Cesium？确认 VITE_FEATURE_GIS=true 并重启 dev。',
+      },
+    ],
+  },
+  {
+    id: 'routes',
+    title: '约定式路由',
+    tagline: '不用手写 routes',
+    blocks: [
+      {
+        type: 'p',
+        text: 'src/views 下每个 .vue 自动注册为路由（Hash 模式）。',
+      },
+      {
+        type: 'table',
+        headers: ['文件', '访问路径'],
+        rows: [
+          ['src/views/index.vue', '/#/'],
+          ['src/views/UserList/index.vue', '/#/user-list'],
+          ['src/views/examples/test/index.vue', '/#/examples/test'],
+        ],
+      },
+      {
+        type: 'p',
+        text: 'examples/ 目录仅开发环境可用，生产 build 会自动排除。',
+      },
+    ],
+  },
+  {
+    id: 'dirs',
+    title: '目录结构',
+    tagline: '代码放哪里',
+    blocks: [
+      {
+        type: 'code',
+        text: 'src/views/       业务页面\nsrc/components/  公共组件\nsrc/api/          接口请求\nsrc/stores/       Pinia\nsrc/utils/        工具 & composables\ninterface/        业务类型\ndocs/             Markdown 文档',
+      },
+    ],
+  },
+  {
+    id: 'alias',
+    title: '路径别名',
+    tagline: 'import 写法',
+    blocks: [
+      {
+        type: 'code',
+        text: "import { useCounterStore } from '@stores/useCounter';\nimport { useFeatureGis } from '@composables/useFeatureGis';\nimport MyCard from '@components/MyCard/index.vue';",
+      },
+      {
+        type: 'ul',
+        items: [
+          '@/ → src/',
+          '@api/ @stores/ @utils/ @views/ @layout/',
+          '完整列表见 tsconfig.json → paths',
+        ],
+      },
+    ],
+  },
+  {
+    id: 'api',
+    title: '接口与代理',
+    tagline: '调后端',
+    blocks: [
+      {
+        type: 'p',
+        text: '接口代码放在 src/api/。开发环境请求 /demo 会代理到 VITE_DEMO_PROXY_TARGET。',
+      },
+      {
+        type: 'code',
+        text: '# 从 OpenAPI 生成客户端\npnpm gen:api',
+      },
+    ],
+  },
+  {
+    id: 'gis',
+    title: 'GIS / Cesium',
+    tagline: '可选三维能力',
+    blocks: [
+      {
+        type: 'p',
+        text: '脚手架 --gis 创建，或 .env 开启 VITE_FEATURE_GIS=true。',
+      },
+      {
+        type: 'code',
+        text: "import CesiumViewer from '@components/CesiumViewer/index.vue';\n// 或\nimport { createViewer } from '@utils/cesium';",
+      },
+      {
+        type: 'links',
+        items: [{ label: '打开 Cesium 示例页 →', to: '/examples/cesium' }],
+      },
+    ],
+  },
+  {
+    id: 'commands',
+    title: '常用命令',
+    tagline: '日常开发',
+    blocks: [
+      {
+        type: 'table',
+        headers: ['命令', '作用'],
+        rows: [
+          ['pnpm dev', '本地开发'],
+          ['pnpm build', '生产构建 → dist/'],
+          ['pnpm typecheck', 'TypeScript 检查'],
+          ['pnpm verify', 'typecheck + lint（提交前）'],
+          ['pnpm test:run', '单元测试'],
+        ],
+      },
+    ],
+  },
+  {
+    id: 'workflow',
+    title: '推荐工作流',
+    tagline: '从这里开始业务',
+    blocks: [
+      {
+        type: 'ul',
+        items: [
+          '1. cp .env.example .env，配置代理与 GIS',
+          '2. pnpm dev，浏览本页示例与 Store 演示',
+          '3. 在 src/views/ 新建业务目录',
+          '4. 补充 src/api/、src/stores/',
+          '5. 提交前 pnpm verify',
+        ],
+      },
+      {
+        type: 'links',
+        items: [
+          { label: 'Store / Alert 示例 →', to: '/examples/test' },
+          { label: '返回首页 →', to: '/' },
+        ],
+      },
+    ],
+  },
+];

package/template/src/directive/focus.ts

@@ -1,9 +1,9 @@
-import type { Directive } from 'vue';
-
-const focus: Directive = {
-  mounted(el) {
-    el.focus();
-  },
-};
-
-export default focus;
+import type { Directive } from 'vue';
+
+const focus: Directive = {
+  mounted(el) {
+    el.focus();
+  },
+};
+
+export default focus;

package/template/src/layout/BasicLayout.vue

@@ -1,28 +1,28 @@
-<template>
-  <div class="layout">
-    <header class="layout-header">{{ title }}</header>
-    <main class="layout-content">
-      <slot />
-    </main>
-  </div>
-</template>
-
-<script setup lang="ts">
-defineProps<{ title?: string }>();
-</script>
-
-<style scoped>
-.layout {
-  min-height: 100vh;
-  background: #f6f7fb;
-}
-
-.layout-header {
-  padding: 16px;
-  font-weight: 600;
-}
-
-.layout-content {
-  padding: 16px;
-}
-</style>
+<template>
+  <div class="layout">
+    <header class="layout-header">{{ title }}</header>
+    <main class="layout-content">
+      <slot />
+    </main>
+  </div>
+</template>
+
+<script setup lang="ts">
+defineProps<{ title?: string }>();
+</script>
+
+<style scoped>
+.layout {
+  min-height: 100vh;
+  background: #f6f7fb;
+}
+
+.layout-header {
+  padding: 16px;
+  font-weight: 600;
+}
+
+.layout-content {
+  padding: 16px;
+}
+</style>

package/template/src/main.ts

@@ -1,33 +1,25 @@
-import { createApp } from 'vue';
-import { createPinia } from 'pinia';
-
-import './styles/global.css';
-import './styles/alerts.less';
-
-import ElementPlus from 'element-plus';
-import zhCn from 'element-plus/es/locale/lang/zh-cn';
-import 'element-plus/dist/index.css';
-
-import App from './App.vue';
-import 'amfe-flexible';
-import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';
-
-import router from '@/router';
-import globalComponents from '@/utils/components';
-import AlertPlugin from '@/utils/alert';
-import focus from '@/directive/focus';
-
-const app = createApp(App);
-const pinia = createPinia();
-pinia.use(piniaPluginPersistedstate);
-
-app.use(ElementPlus, {
-  locale: zhCn,
-});
-app.use(pinia);
-app.use(router);
-app.use(globalComponents);
-app.use(AlertPlugin);
-app.directive('focus', focus);
-
-app.mount('#app');
+import { createApp } from 'vue';
+import { createPinia } from 'pinia';
+
+import './styles/global.css';
+import './styles/shell.css';
+import './styles/alerts.less';
+
+import App from './App.vue';
+import piniaPluginPersistedstate from 'pinia-plugin-persistedstate';
+
+import router from '@/router';
+import globalComponents from '@/utils/components';
+import AlertPlugin from '@/utils/alert';
+import focus from '@/directive/focus';
+
+const app = createApp(App);
+const pinia = createPinia();
+pinia.use(piniaPluginPersistedstate);
+app.use(pinia);
+app.use(router);
+app.use(globalComponents);
+app.use(AlertPlugin);
+app.directive('focus', focus);
+
+app.mount('#app');

package/template/src/router/index.ts

@@ -1,24 +1,30 @@
-import { createRouter, createWebHashHistory } from 'vue-router';
-
-const pages = import.meta.glob('../views/**/*.vue');
-
-const routes = Object.keys(pages).map((path) => {
-  const routePath = path
-    .replace(/..\/views/, '')
-    .replace(/\.\w+$/, '')
-    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-    .toLowerCase()
-    .replace(/index$/, '');
-
-  return {
-    path: routePath,
-    component: pages[path],
-  };
-});
-
-const router = createRouter({
-  history: createWebHashHistory(),
-  routes,
-});
-
-export default router;
+import {
+  createRouter,
+  createWebHashHistory,
+  type RouteRecordRaw,
+} from 'vue-router';
+import { filePathToRoute, isExampleRoute } from './routeUtils';
+
+const pages = import.meta.glob('../views/**/*.vue');
+
+const routes: RouteRecordRaw[] = Object.keys(pages)
+  .filter((filePath) => {
+    if (import.meta.env.PROD && isExampleRoute(filePath)) {
+      return false;
+    }
+    return true;
+  })
+  .map((filePath) => ({
+    path: filePathToRoute(filePath),
+    component: pages[filePath],
+    meta: {
+      isExample: isExampleRoute(filePath),
+    },
+  }));
+
+const router = createRouter({
+  history: createWebHashHistory(),
+  routes,
+});
+
+export default router;

package/template/src/router/routeUtils.ts

@@ -0,0 +1,13 @@
+/** 约定式路由：views 文件路径 → URL path */
+export function isExampleRoute(filePath: string): boolean {
+  return /\/(examples|_examples)\//.test(filePath);
+}
+
+export function filePathToRoute(filePath: string): string {
+  return filePath
+    .replace(/..\/views/, '')
+    .replace(/\.\w+$/, '')
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/\/index$/, '');
+}

package/template/src/stores/README.md

@@ -1,3 +1,3 @@
-# stores
-
-全局状态管理放在这里。
+# stores
+
+全局状态管理放在这里。

package/template/src/stores/useCounter.ts

@@ -1,12 +1,12 @@
-import { defineStore } from 'pinia';
-
-export const useCounterStore = defineStore('counter', {
-  state: () => ({
-    count: 0,
-  }),
-  actions: {
-    inc() {
-      this.count += 1;
-    },
-  },
-});
+import { defineStore } from 'pinia';
+
+export const useCounterStore = defineStore('counter', {
+  state: () => ({
+    count: 0,
+  }),
+  actions: {
+    inc() {
+      this.count += 1;
+    },
+  },
+});

package/template/src/styles/alerts.less

@@ -1,85 +1,85 @@
-// 定义颜色变量
-@success-color: #67c23a;
-@warning-color: #e6a23c;
-@error-color: #f56c6c;
-@info-color: #909399;
-@text-color: #fff;
-@shadow-color: rgba(0, 0, 0, 0.1);
-
-// 基础字体大小和间距
-@font-size: 16px;
-@padding: 10px 20px;
-
-// 动画渐变定义
-@keyframes fadeIn {
-  from {
-    opacity: 0;
-  }
-  to {
-    opacity: 1;
-  }
-}
-
-@keyframes fadeOut {
-  from {
-    opacity: 1;
-  }
-  to {
-    opacity: 0;
-  }
-}
-
-.alerts-container {
-  position: fixed;
-  top: 20px;
-  left: 50%;
-  transform: translateX(-50%);
-  z-index: 9999;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  gap: 10px;
-}
-
-.alert {
-  padding: @padding;
-  color: @text-color;
-  border-radius: 5px;
-  box-shadow: 0 2px 8px @shadow-color;
-  font-size: @font-size;
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: 10px;
-  width: 250px;
-  animation: fadeIn 0.5s ease-out;
-
-  div:last-child {
-    font-size: larger;
-    cursor: pointer;
-    user-select: none;
-    line-height: 100%;
-    vertical-align: middle;
-    transform: translateX(5px);
-
-    &:hover {
-      color: #f4f4f4;
-    }
-  }
-}
-
-.alert-success {
-  background-color: @success-color;
-}
-
-.alert-warning {
-  background-color: @warning-color;
-}
-
-.alert-error {
-  background-color: @error-color;
-}
-
-.alert-info {
-  background-color: @info-color;
-}
+// 定义颜色变量
+@success-color: #67c23a;
+@warning-color: #e6a23c;
+@error-color: #f56c6c;
+@info-color: #909399;
+@text-color: #fff;
+@shadow-color: rgba(0, 0, 0, 0.1);
+
+// 基础字体大小和间距
+@font-size: 16px;
+@padding: 10px 20px;
+
+// 动画渐变定义
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes fadeOut {
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+.alerts-container {
+  position: fixed;
+  top: 20px;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: 9999;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 10px;
+}
+
+.alert {
+  padding: @padding;
+  color: @text-color;
+  border-radius: 5px;
+  box-shadow: 0 2px 8px @shadow-color;
+  font-size: @font-size;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  width: 250px;
+  animation: fadeIn 0.5s ease-out;
+
+  div:last-child {
+    font-size: larger;
+    cursor: pointer;
+    user-select: none;
+    line-height: 100%;
+    vertical-align: middle;
+    transform: translateX(5px);
+
+    &:hover {
+      color: #f4f4f4;
+    }
+  }
+}
+
+.alert-success {
+  background-color: @success-color;
+}
+
+.alert-warning {
+  background-color: @warning-color;
+}
+
+.alert-error {
+  background-color: @error-color;
+}
+
+.alert-info {
+  background-color: @info-color;
+}