create-swdg-frontend 0.1.7 → 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/main.ts

@@ -2,6 +2,7 @@ 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';

package/template/src/router/index.ts

@@ -1,20 +1,26 @@
-import { createRouter, createWebHashHistory } from 'vue-router';
+import {
+  createRouter,
+  createWebHashHistory,
+  type RouteRecordRaw,
+} from 'vue-router';
+import { filePathToRoute, isExampleRoute } from './routeUtils';
 
 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 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(),

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/styles/shell.css

@@ -0,0 +1,232 @@
+:root {
+  --shell-bg: #0f172a;
+  --shell-surface: #ffffff;
+  --shell-muted: #64748b;
+  --shell-text: #0f172a;
+  --shell-accent: #2563eb;
+  --shell-accent-soft: #dbeafe;
+  --shell-border: #e2e8f0;
+  --shell-radius: 12px;
+  --shell-shadow: 0 12px 40px rgb(15 23 42 / 12%);
+}
+
+.shell-page {
+  min-height: 100vh;
+  background: linear-gradient(160deg, #0f172a 0%, #1e3a5f 45%, #0f172a 100%);
+  color: var(--shell-text);
+}
+
+.shell-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px 28px;
+  color: #f8fafc;
+  border-bottom: 1px solid rgb(255 255 255 / 8%);
+  backdrop-filter: blur(8px);
+}
+
+.shell-header__brand {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.shell-header__title {
+  margin: 0;
+  font-size: 18px;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+}
+
+.shell-header__tag {
+  font-size: 12px;
+  color: #94a3b8;
+}
+
+.shell-main {
+  max-width: 960px;
+  margin: 0 auto;
+  padding: 40px 24px 64px;
+}
+
+.shell-hero {
+  margin-bottom: 32px;
+  padding: 32px;
+  border-radius: var(--shell-radius);
+  background: var(--shell-surface);
+  box-shadow: var(--shell-shadow);
+}
+
+.shell-hero h2 {
+  margin: 0 0 8px;
+  font-size: 26px;
+  font-weight: 700;
+  color: var(--shell-text);
+}
+
+.shell-hero p {
+  margin: 0;
+  line-height: 1.6;
+  color: var(--shell-muted);
+}
+
+.shell-hero code {
+  padding: 2px 8px;
+  border-radius: 6px;
+  background: var(--shell-accent-soft);
+  color: var(--shell-accent);
+  font-size: 13px;
+}
+
+.shell-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+  gap: 16px;
+}
+
+.shell-card {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 20px;
+  border-radius: var(--shell-radius);
+  background: var(--shell-surface);
+  border: 1px solid var(--shell-border);
+  box-shadow: var(--shell-shadow);
+  text-decoration: none;
+  color: inherit;
+  transition:
+    transform 0.2s ease,
+    box-shadow 0.2s ease,
+    border-color 0.2s ease;
+}
+
+.shell-card:hover {
+  transform: translateY(-2px);
+  border-color: var(--shell-accent);
+  box-shadow: 0 16px 48px rgb(37 99 235 / 18%);
+}
+
+.shell-card__icon {
+  font-size: 28px;
+  line-height: 1;
+}
+
+.shell-card__title {
+  margin: 0;
+  font-size: 16px;
+  font-weight: 600;
+}
+
+.shell-card__desc {
+  margin: 0;
+  font-size: 13px;
+  color: var(--shell-muted);
+  line-height: 1.5;
+}
+
+.shell-card__arrow {
+  margin-top: auto;
+  font-size: 13px;
+  font-weight: 500;
+  color: var(--shell-accent);
+}
+
+.shell-badge {
+  display: inline-block;
+  padding: 4px 10px;
+  border-radius: 999px;
+  font-size: 11px;
+  font-weight: 500;
+  background: #fef3c7;
+  color: #92400e;
+}
+
+.shell-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 8px 16px;
+  border: none;
+  border-radius: 8px;
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: background 0.15s ease;
+}
+
+.shell-btn--ghost {
+  background: rgb(255 255 255 / 12%);
+  color: #f8fafc;
+}
+
+.shell-btn--ghost:hover {
+  background: rgb(255 255 255 / 20%);
+}
+
+.shell-btn--primary {
+  background: var(--shell-accent);
+  color: #fff;
+}
+
+.shell-btn--primary:hover {
+  background: #1d4ed8;
+}
+
+.example-toolbar {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-shrink: 0;
+  padding: 12px 20px;
+  background: var(--shell-surface);
+  border-bottom: 1px solid var(--shell-border);
+  box-shadow: 0 1px 0 rgb(15 23 42 / 4%);
+}
+
+.example-toolbar__title {
+  flex: 1;
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--shell-muted);
+}
+
+.example-panel {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 16px;
+  min-height: calc(100vh - 52px);
+  padding: 32px 24px;
+  background: linear-gradient(180deg, #f8fafc 0%, #e2e8f0 100%);
+}
+
+.example-panel__card {
+  width: min(420px, 100%);
+  padding: 32px;
+  border-radius: var(--shell-radius);
+  background: var(--shell-surface);
+  box-shadow: var(--shell-shadow);
+  text-align: center;
+}
+
+.example-panel__card h1 {
+  margin: 12px 0 8px;
+  font-size: 22px;
+}
+
+.example-panel__counter {
+  font-size: 32px;
+  font-weight: 700;
+  color: var(--shell-accent);
+  margin: 8px 0 20px;
+}
+
+.example-panel__actions {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  justify-content: center;
+}

package/template/src/utils/axios-middleware.js

@@ -55,7 +55,7 @@ const extractApiPath = (url) => {
   return match ? match[1] : 'Unknown API';
 };
 
-const handleBusinessError = (response) => {
+const _handleBusinessError = (response) => {
   if (response.data.code === 0) {
     const apiPath = extractApiPath(response.config.url);
     if (process.env.NODE_ENV === 'development') {

package/template/src/utils/cesium/index.ts

@@ -0,0 +1,71 @@
+import {
+  EllipsoidTerrainProvider,
+  Ion,
+  OpenStreetMapImageryProvider,
+  Viewer,
+  type ImageryProvider,
+} from 'cesium';
+import 'cesium/Build/Cesium/Widgets/widgets.css';
+
+let configured = false;
+
+/** Apply ion token when provided (optional; default map does not require Ion). */
+export function configureCesium(): void {
+  if (configured) return;
+
+  const token = import.meta.env.VITE_CESIUM_ION_ACCESS_TOKEN;
+  if (token) {
+    Ion.defaultAccessToken = token;
+  }
+
+  configured = true;
+}
+
+/** OpenStreetMap 栅格底图（开源、免费，无需 Ion token）。 */
+export function createOsmImageryProvider(): ImageryProvider {
+  return new OpenStreetMapImageryProvider({
+    url: 'https://tile.openstreetmap.org/',
+  });
+}
+
+const defaultUiOptions: Viewer.ConstructorOptions = {
+  animation: false,
+  timeline: false,
+  baseLayerPicker: false,
+  geocoder: false,
+  homeButton: false,
+  sceneModePicker: false,
+  navigationHelpButton: false,
+  fullscreenButton: false,
+  // 不加载 Ion 默认影像（无 token 时易出现 InvalidStateError: image decode）
+  baseLayer: false,
+  terrainProvider: new EllipsoidTerrainProvider(),
+};
+
+export function createViewer(
+  container: HTMLElement | string,
+  options?: Viewer.ConstructorOptions
+): Viewer {
+  configureCesium();
+
+  const { baseLayer, ...rest } = options ?? {};
+  const useCustomBaseLayer = baseLayer !== undefined && baseLayer !== false;
+
+  const viewer = new Viewer(container, {
+    ...defaultUiOptions,
+    ...rest,
+    baseLayer: useCustomBaseLayer ? baseLayer : false,
+  });
+
+  if (!useCustomBaseLayer) {
+    viewer.imageryLayers.removeAll();
+    viewer.imageryLayers.addImageryProvider(createOsmImageryProvider());
+  }
+
+  return viewer;
+}
+
+export function destroyViewer(viewer: Viewer | null | undefined): void {
+  if (!viewer || viewer.isDestroyed()) return;
+  viewer.destroy();
+}

package/template/src/utils/composables/useFeatureGis.ts

@@ -0,0 +1,24 @@
+import { computed } from 'vue';
+
+/** 纯函数，便于单测 */
+export function resolveFeatureGis(
+  flag: string | undefined,
+  isDev: boolean
+): boolean {
+  if (flag === 'true') return true;
+  if (flag === 'false') return false;
+  return isDev;
+}
+
+/**
+ * GIS 是否可用：
+ * - 显式 VITE_FEATURE_GIS=true / false
+ * - 开发环境未配置时默认 true（模板仓库自带 Cesium，避免漏配 .env）
+ */
+export function useFeatureGis() {
+  const hasGis = computed(() =>
+    resolveFeatureGis(import.meta.env.VITE_FEATURE_GIS, import.meta.env.DEV)
+  );
+
+  return { hasGis };
+}

package/template/src/views/examples/cesium/index.vue

@@ -0,0 +1,85 @@
+<template>
+  <div class="cesium-page">
+    <header class="example-toolbar">
+      <button
+        type="button"
+        class="shell-btn shell-btn--ghost cesium-toolbar__back"
+        @click="goBack"
+      >
+        ← 首页
+      </button>
+      <span class="example-toolbar__title">Cesium · OpenStreetMap</span>
+      <span v-if="!hasGis" class="shell-badge">GIS 未在 .env 启用</span>
+    </header>
+    <div v-if="!hasGis" class="cesium-page__fallback">
+      <p>
+        请在 <code>.env</code> 中设置 <code>VITE_FEATURE_GIS=true</code> 并重启
+        <code>pnpm dev</code>。
+      </p>
+      <button
+        type="button"
+        class="shell-btn shell-btn--primary"
+        @click="goBack"
+      >
+        返回首页
+      </button>
+    </div>
+    <CesiumViewer v-else class="cesium-page__viewer" />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { useRouter } from 'vue-router';
+import CesiumViewer from '@components/CesiumViewer/index.vue';
+import { useFeatureGis } from '@composables/useFeatureGis';
+
+const router = useRouter();
+const { hasGis } = useFeatureGis();
+
+const goBack = () => {
+  router.push('/');
+};
+</script>
+
+<style scoped>
+.cesium-page {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100vh;
+  overflow: hidden;
+  background: #0b1220;
+}
+
+.cesium-toolbar__back {
+  background: #f1f5f9;
+  color: var(--shell-text);
+}
+
+.cesium-toolbar__back:hover {
+  background: #e2e8f0;
+}
+
+.cesium-page__viewer {
+  flex: 1;
+  min-height: 0;
+}
+
+.cesium-page__fallback {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 16px;
+  padding: 24px;
+  color: #e2e8f0;
+  text-align: center;
+}
+
+.cesium-page__fallback code {
+  padding: 2px 6px;
+  border-radius: 4px;
+  background: rgb(255 255 255 / 10%);
+}
+</style>