create-swdg-frontend 0.1.6 → 0.2.0

package/template/docs/TESTING.md

@@ -0,0 +1,104 @@
+# 测试与发布门禁
+
+发布 `create-swdg-frontend` / `swdg` 到 npmjs **前必须** 通过完整测试管道。本地与 CI 使用同一套命令。
+
+## 命令一览
+
+| 命令                 | 用途                                    | 何时跑            |
+| -------------------- | --------------------------------------- | ----------------- |
+| `pnpm verify`        | typecheck + eslint                      | 日常提交前        |
+| `pnpm test:unit`     | Vitest 单元测试                         | 开发中            |
+| `pnpm test:scaffold` | 脚手架集成（无 install）                | 改 create-swdg 后 |
+| `pnpm test:template` | sync + template install/typecheck/build | 改模板后          |
+| **`pnpm test:ci`**   | **完整发布门禁（四阶段）**              | **PR / 发布前**   |
+
+## 发布门禁管道（`pnpm test:ci`）
+
+顺序固定，任一失败即 `exit 1`：
+
+```
+1. verify      根项目 typecheck + eslint
+2. unit        vitest 单元测试
+3. scaffold    --no-gis / --gis 产物、manifest、CLI  smoke
+4. template    sync-template → template 目录 install → typecheck → build
+```
+
+`pnpm release x.y.z` 会在改版本号、打 npm 包 **之前** 自动执行 `test:ci`。
+
+`create-swdg` 的 `prepublishOnly` 会 sync + `test:template`（防止单独 publish 时模板未验证）。
+
+## 单元测试范围
+
+位于 `tests/unit/`：
+
+| 文件                       | 覆盖                          |
+| -------------------------- | ----------------------------- |
+| `router.utils.test.ts`     | 约定式路由、examples 过滤规则 |
+| `scaffold.lib.test.ts`     | CLI argv、包名校验            |
+| `useFeatureGis.test.ts`    | GIS feature flag 逻辑         |
+| `onboardingSlides.test.ts` | onboarding 幻灯片数据结构     |
+
+## 集成测试（scaffold）
+
+`scripts/test-scaffold.mjs` 在系统临时目录生成项目，断言：
+
+**--no-gis**
+
+- 无 `cesium` / `vite-plugin-static-copy` 依赖
+- 删除 Cesium 相关目录与脚本
+- `.env.example` 无 `VITE_FEATURE_GIS=true`
+- `.swdg/manifest.json` → `features.gis: false`
+
+**--gis**
+
+- 保留 cesium 示例页与 env 配置
+- `manifest.features.gis: true`
+
+**CLI**
+
+- 合法参数能退出 0
+- 非法项目名退出非 0
+
+## 模板测试（template）
+
+`scripts/test-template.mjs`：
+
+1. 从 monorepo 根 sync 到 `create-swdg/template`
+2. 检查必要文件存在
+3. `pnpm install` + `typecheck` + `build`（带 `VITE_FEATURE_GIS=true`）
+
+确保 npm 包内 template **能真实构建**。
+
+## CI
+
+GitHub Actions `.github/workflows/ci.yml`：
+
+```yaml
+pnpm install --frozen-lockfile
+pnpm test:ci
+```
+
+## 推荐工作流
+
+```bash
+# 日常
+pnpm verify
+
+# 改脚手架 / 模板后
+pnpm test:scaffold
+pnpm test:template
+
+# 发布前（与 CI 一致）
+pnpm test:ci
+pnpm release 0.2.1
+```
+
+## 故障排查
+
+| 失败阶段 | 常见原因                                         |
+| -------- | ------------------------------------------------ |
+| verify   | TS 错误、ESLint、单元测试红                      |
+| scaffold | GIS 剥离不完整、manifest 版本与 constants 不一致 |
+| template | 未 sync、template build 失败（Cesium/路由等）    |
+
+template 阶段最慢（install + build），本地可先 `pnpm test:scaffold` 快速迭代脚手架逻辑。

package/template/eslint.config.js

@@ -1,96 +1,97 @@
-import { FlatCompat } from '@eslint/eslintrc';
-import js from '@eslint/js';
-import { fileURLToPath } from 'node:url';
-import { dirname } from 'node:path';
-import tseslint from '@typescript-eslint/eslint-plugin';
-import tsParser from '@typescript-eslint/parser';
-import vue from 'eslint-plugin-vue';
-import vueParser from 'vue-eslint-parser';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-const compat = new FlatCompat({
-  baseDirectory: __dirname,
-  recommendedConfig: js.configs.recommended,
-  allConfig: js.configs.all,
-});
-
-export default [
-  {
-    ignores: [
-      'dist',
-      'out',
-      'node_modules',
-      'index.html',
-      '*.d.ts',
-      '.env',
-      '.env.local',
-      '.env.*.local',
-      'src/components.d.ts',
-      'public/**',
-      'dev-dist',
-    ],
-  },
-  ...compat.extends(
-    'eslint:recommended',
-    'plugin:@typescript-eslint/recommended',
-    'plugin:prettier/recommended'
-  ),
-  ...vue.configs['flat/recommended'],
-  {
-    plugins: {
-      vue,
-      '@typescript-eslint': tseslint,
-    },
-    languageOptions: {
-      parser: vueParser,
-      parserOptions: {
-        parser: tsParser,
-        ecmaVersion: 2021,
-        sourceType: 'module',
-      },
-    },
-    rules: {
-      'require-jsdoc': 'off',
-      'no-unused-vars': 'off',
-      '@typescript-eslint/no-unused-vars': [
-        'warn',
-        {
-          argsIgnorePattern: '^_',
-          varsIgnorePattern: '^_',
-        },
-      ],
-      'no-console': 'off',
-      'vue/no-unused-components': 'warn',
-      '@typescript-eslint/no-explicit-any': 'off',
-      '@typescript-eslint/explicit-module-boundary-types': 'off',
-      'prettier/prettier': ['error', {}, { usePrettierrc: true }],
-      'vue/multi-word-component-names': 'off',
-      '@typescript-eslint/ban-ts-comment': [
-        'error',
-        {
-          'ts-ignore': 'allow-with-description',
-          'ts-expect-error': 'allow-with-description',
-          'ts-nocheck': true,
-          'ts-check': false,
-        },
-      ],
-      'vue/attribute-hyphenation': 'off',
-      'vue/html-closing-bracket-newline': 'off',
-      'vue/html-indent': 'off',
-      'vue/max-attributes-per-line': 'off',
-      'vue/multiline-html-element-content-newline': 'off',
-      'vue/no-mutating-props': 'off',
-      'vue/singleline-html-element-content-newline': 'off',
-      'no-undef': 'off',
-      'spaced-comment': 'off',
-    },
-  },
-  {
-    files: ['**/*.cjs'],
-    rules: {
-      '@typescript-eslint/no-require-imports': 'off',
-    },
-  },
-];
+import { FlatCompat } from '@eslint/eslintrc';
+import js from '@eslint/js';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import tseslint from '@typescript-eslint/eslint-plugin';
+import tsParser from '@typescript-eslint/parser';
+import vue from 'eslint-plugin-vue';
+import vueParser from 'vue-eslint-parser';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+  recommendedConfig: js.configs.recommended,
+  allConfig: js.configs.all,
+});
+
+export default [
+  {
+    ignores: [
+      'dist',
+      'out',
+      'node_modules',
+      'index.html',
+      '*.d.ts',
+      '.env',
+      '.env.local',
+      '.env.*.local',
+      'src/components.d.ts',
+      'public/**',
+      'src/api/**',
+      'dev-dist',
+    ],
+  },
+  ...compat.extends(
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:prettier/recommended'
+  ),
+  ...vue.configs['flat/recommended'],
+  {
+    plugins: {
+      vue,
+      '@typescript-eslint': tseslint,
+    },
+    languageOptions: {
+      parser: vueParser,
+      parserOptions: {
+        parser: tsParser,
+        ecmaVersion: 2021,
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      'require-jsdoc': 'off',
+      'no-unused-vars': 'off',
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+        },
+      ],
+      'no-console': 'off',
+      'vue/no-unused-components': 'warn',
+      '@typescript-eslint/no-explicit-any': 'off',
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+      'prettier/prettier': ['error', {}, { usePrettierrc: true }],
+      'vue/multi-word-component-names': 'off',
+      '@typescript-eslint/ban-ts-comment': [
+        'error',
+        {
+          'ts-ignore': 'allow-with-description',
+          'ts-expect-error': 'allow-with-description',
+          'ts-nocheck': true,
+          'ts-check': false,
+        },
+      ],
+      'vue/attribute-hyphenation': 'off',
+      'vue/html-closing-bracket-newline': 'off',
+      'vue/html-indent': 'off',
+      'vue/max-attributes-per-line': 'off',
+      'vue/multiline-html-element-content-newline': 'off',
+      'vue/no-mutating-props': 'off',
+      'vue/singleline-html-element-content-newline': 'off',
+      'no-undef': 'off',
+      'spaced-comment': 'off',
+    },
+  },
+  {
+    files: ['**/*.cjs'],
+    rules: {
+      '@typescript-eslint/no-require-imports': 'off',
+    },
+  },
+];

package/template/index.html

@@ -1,17 +1,17 @@
-<!DOCTYPE html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="UTF-8" />
-    <link rel="icon" type="image/svg+xml" href="/src/assets/favicon.svg" />
-    <meta
-      name="viewport"
-      content="width=device-width, initial-scale=1, viewport-fit=cover"
-    />
-    <title>物联网地下水位监测系统</title>
-  </head>
-  <body>
-    <div hidden>Copyright © 2026 四川水发勘测设计研究有限公司</div>
-    <div id="app"></div>
-    <script type="module" src="/src/main.ts"></script>
-  </body>
-</html>
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/src/assets/favicon.svg" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1, viewport-fit=cover"
+    />
+    <title>物联网地下水位监测系统</title>
+  </head>
+  <body>
+    <div hidden>Copyright © 2026 四川水发勘测设计研究有限公司</div>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template/interface/user.ts

@@ -1,5 +1,5 @@
-export interface User {
-  id: string;
-  name: string;
-  role: 'admin' | 'member';
-}
+export interface User {
+  id: string;
+  name: string;
+  role: 'admin' | 'member';
+}

package/template/package.json

@@ -1,86 +1,88 @@
-{
-  "name": "frontend-framework",
-  "private": true,
-  "version": "0.0.0",
-  "type": "module",
-  "author": "inupedia",
-  "scripts": {
-    "prepare": "husky install",
-    "dev": "vite",
-    "build": "vue-tsc -b && vite build",
-    "preview": "vite preview",
-    "lint": "eslint src tests --ext .ts,.vue",
-    "lint:fix": "eslint src tests --ext .ts,.vue --fix",
-    "prettier": "prettier --check .",
-    "prettier:fix": "prettier --write .",
-    "gen:api": "node ./scripts/gen-api.cjs",
-    "release": "node scripts/release.mjs",
-    "test": "vitest",
-    "test:run": "vitest run"
-  },
-  "husky": {
-    "hooks": {
-      "pre-commit": "npx lint-staged"
-    }
-  },
-  "lint-staged": {
-    "*.{js,jsx,ts,tsx,vue}": [
-      "eslint --fix",
-      "prettier --write"
-    ],
-    "*.{css,scss,less,html,md,json,yml,yaml}": [
-      "prettier --write"
-    ]
-  },
-  "dependencies": {
-    "amfe-flexible": "^2.2.1",
-    "axios": "^1.13.2",
-    "echarts": "^6.0.0",
-    "element-plus": "^2.13.1",
-    "lint-staged": "^16.2.7",
-    "pinia": "^3.0.4",
-    "pinia-plugin-persistedstate": "^4.7.1",
-    "vue": "^3.5.26",
-    "vue-router": "^4.6.4"
-  },
-  "devDependencies": {
-    "@commitlint/cli": "^20.3.1",
-    "@commitlint/config-conventional": "^20.3.1",
-    "@commitlint/lint": "^20.3.1",
-    "@commitlint/load": "^20.3.1",
-    "@eslint/eslintrc": "^3.3.3",
-    "@eslint/js": "^9.39.2",
-    "@openapitools/openapi-generator-cli": "^2.21.0",
-    "@typescript-eslint/eslint-plugin": "^8.53.0",
-    "@typescript-eslint/parser": "^8.53.0",
-    "@vitejs/plugin-vue": "^6.0.3",
-    "@vue/tsconfig": "^0.8.1",
-    "eslint": "^9.39.2",
-    "eslint-config-google": "^0.14.0",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-prettier": "^5.5.5",
-    "eslint-plugin-vue": "^10.7.0",
-    "fs-extra": "^11.3.3",
-    "husky": "^9.1.7",
-    "jsdom": "^27.4.0",
-    "less": "^4.5.1",
-    "less-loader": "^12.3.0",
-    "postcss-pxtorem": "^6.1.0",
-    "prettier": "^3.8.0",
-    "rollup-plugin-copy": "^3.5.0",
-    "sass-embedded": "^1.97.2",
-    "stylelint": "^16.26.1",
-    "stylelint-config-recommended-vue": "^1.6.1",
-    "stylelint-config-standard": "^36.0.0",
-    "typescript": "~5.9.3",
-    "unplugin-auto-import": "^21.0.0",
-    "unplugin-vue-components": "^31.0.0",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.17",
-    "vue-eslint-parser": "^10.0.0",
-    "vue-tsc": "^3.2.2"
-  },
-  "volta": {
-    "node": "22.17.0"
-  }
-}
+{
+  "name": "frontend-framework",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "author": "inupedia",
+  "scripts": {
+    "prepare": "husky install",
+    "dev": "vite",
+    "build": "vue-tsc -b && vite build",
+    "preview": "vite preview",
+    "typecheck": "vue-tsc -b --pretty false",
+    "lint": "eslint src tests --ext .ts,.vue",
+    "lint:fix": "eslint src tests --ext .ts,.vue --fix",
+    "lint:style": "stylelint \"src/**/*.{vue,css,less,scss}\"",
+    "lint:all": "npm run lint && npm run lint:style && npm run prettier",
+    "prettier": "prettier --check .",
+    "prettier:fix": "prettier --write .",
+    "gen:api": "node ./scripts/gen-api.cjs",
+    "release": "node scripts/release.mjs",
+    "test": "vitest",
+    "test:unit": "vitest run",
+    "test:run": "vitest run",
+    "test:scaffold": "node scripts/test-scaffold.mjs",
+    "test:template": "node scripts/test-template.mjs",
+    "test:ci": "node scripts/test-pipeline.mjs",
+    "verify": "node scripts/verify.mjs"
+  },
+  "engines": {
+    "node": ">=22",
+    "pnpm": ">=9"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "npx lint-staged"
+    }
+  },
+  "dependencies": {
+    "axios": "^1.16.1",
+    "cesium": "^1.141.0",
+    "pinia": "^3.0.4",
+    "pinia-plugin-persistedstate": "^4.7.1",
+    "vue": "^3.5.34",
+    "vue-router": "^5.0.7"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^21.0.1",
+    "@commitlint/config-conventional": "^21.0.1",
+    "@commitlint/lint": "^21.0.1",
+    "@commitlint/load": "^21.0.1",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@openapitools/openapi-generator-cli": "^2.34.0",
+    "@typescript-eslint/eslint-plugin": "^8.59.4",
+    "@typescript-eslint/parser": "^8.59.4",
+    "@vitejs/plugin-vue": "^6.0.7",
+    "@vue/tsconfig": "^0.9.1",
+    "autoprefixer": "^10.5.0",
+    "eslint": "^10.4.0",
+    "eslint-config-google": "^0.14.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-vue": "^10.9.1",
+    "fs-extra": "^11.3.5",
+    "husky": "^9.1.7",
+    "jsdom": "^29.1.1",
+    "less": "^4.6.4",
+    "lint-staged": "^17.0.5",
+    "prettier": "^3.8.3",
+    "rollup-plugin-copy": "^3.5.0",
+    "sass-embedded": "^1.100.0",
+    "stylelint": "^17.12.0",
+    "stylelint-config-recommended-vue": "^1.6.1",
+    "stylelint-config-standard": "^40.0.0",
+    "typescript": "~6.0.3",
+    "unplugin-auto-import": "^21.0.0",
+    "unplugin-vue-components": "^32.1.0",
+    "vite": "^8.0.14",
+    "vite-plugin-static-copy": "^4.1.0",
+    "vitest": "^4.1.7",
+    "vue-eslint-parser": "^10.4.0",
+    "vue-tsc": "^3.3.1"
+  },
+  "volta": {
+    "node": "22.17.0"
+  },
+  "packageManager": "pnpm@9"
+}