create-swdg-frontend 0.1.7 → 0.2.1

package/template/docs/MAINTAINER.md

@@ -0,0 +1,75 @@
+# 脚手架维护指南（负责人）
+
+对标大厂实践：**薄 CLI、厚模板、特性开关、可验证、可版本化**。
+
+## 架构
+
+```
+frontend-framework/     # 模板源仓库（本仓库）
+├── create-swdg/        # npm 包 create-swdg-frontend（pnpm create swdg-frontend）
+│   ├── bin/index.js    # CLI 入口
+│   ├── lib/            # 提示、特性剥离、manifest
+│   ├── stubs/          # 无 GIS 时的配置替身
+│   └── template/       # sync-template 同步产物
+└── swdg/               # 全局 CLI 包装
+```
+
+## 发布到 npm
+
+### 方式 A：打 tag 自动发布（推荐）
+
+**一次性配置**
+
+1. 登录 [npmjs.com](https://www.npmjs.com/)，确认账号已验证邮箱  
+2. 确认包名 **`create-swdg-frontend`**、**`swdg`** 在你账号下（首次需未被占用）  
+3. npm → Access Tokens → **Generate New Token**  
+   - **必须** 选 **Granular Access Token**（Packages: Read and write）并勾选 **Bypass 2FA**，  
+     或 **Classic Token → Automation**（专为 CI 设计，不需要 OTP）  
+   - ⚠️ 不要用 Classic **Publish** token，CI 会报 `EOTP`  
+4. GitHub → **Settings → Secrets → Actions** → 更新 **`NPM_TOKEN`**
+
+**每次发版**
+
+```bash
+# 1. 提交并推到 GitHub（main 上 CI 会跑 test:ci）
+git push github main
+
+# 2. 打 tag 并推送（版本号与 tag 一致，格式 vX.Y.Z；Release workflow 会再跑 test:ci 后 publish）
+git tag v0.2.1
+git push github v0.2.1
+```
+
+4. 打开 **Actions → Release to npm**，等待 workflow 完成  
+5. 验证：`npm view create-swdg-frontend version`、`npm view swdg version`
+
+CI 会：从 tag 解析版本 → `test:ci` → 发布 `create-swdg-frontend` → 发布 `swdg`。
+
+### 方式 B：本地手动发布
+
+```bash
+pnpm test:ci
+pnpm release 0.2.1
+```
+
+详见 [TESTING.md](./TESTING.md)。
+
+## 特性（Feature Flags）
+
+| 特性  | 默认 | CLI                |
+| ----- | ---- | ------------------ |
+| `gis` | 关闭 | `--gis` / 交互选 Y |
+
+未启用 GIS 时会删除：cesium 依赖、vite 静态资源配置、`src/views/examples/cesium`、相关工具与组件。
+
+生成项目会写入 `.swdg/manifest.json` 记录创建时选项。
+
+## 模板质量门禁
+
+- `examples/` 路由：**生产构建自动排除**（见 `src/router/index.ts`）
+- 创建后可选 **typecheck 校验**（`--verify`）
+- 建议每月 sync 一次并打 tag
+
+## 勿再做的事
+
+- 不要把 Cesium 放进 `public/`（已改为 npm + vite 插件）
+- 不要在业务 `src/views/` 根下堆演示页，统一放 `examples/`

package/template/docs/ONBOARDING.md

@@ -0,0 +1,284 @@
+# 项目使用指南
+
+本文说明 **如何在本仓库或脚手架生成的项目中日常开发**。维护模板、发布 npm 见 [MAINTAINER.md](./MAINTAINER.md)。
+
+---
+
+## 一、两种使用方式
+
+| 方式               | 适合谁                           | 第一步                                                       |
+| ------------------ | -------------------------------- | ------------------------------------------------------------ |
+| **直接使用本仓库** | 团队统一模板、在 monorepo 上迭代 | `git clone` → `pnpm install`                                 |
+| **脚手架新建项目** | 每个业务一条独立仓库             | `pnpm create swdg-frontend my-app`（见根目录 [README](../README.md)） |
+
+两种方式的项目结构、命令、路由约定 **一致**；脚手架可通过 `--gis` / `--no-gis` 裁剪 Cesium 相关文件。
+
+---
+
+## 二、环境要求与首次启动
+
+**要求**
+
+- Node.js **22+**
+- **pnpm** 9+（推荐；也可用 npm / yarn）
+
+**首次启动**
+
+```bash
+pnpm install
+cp .env.example .env    # 必做：复制环境变量
+pnpm dev
+```
+
+浏览器会自动打开（默认 `http://localhost:3000`）。路由为 **Hash 模式**，首页地址形如 `http://localhost:3000/#/`。
+
+**页面内指南**：开发模式下首页自带 **PPT 式翻页**（共 10 页），也可访问 `/#/examples/guide` 全屏阅读。支持方向键、`←` / `→` 按钮与底部圆点跳转。
+
+> 修改 `.env` 后需要 **重启** `pnpm dev`，Vite 才会加载新变量。
+
+---
+
+## 三、环境变量说明
+
+在根目录 `.env` 中配置（参考 `.env.example`）：
+
+| 变量                           | 是否必填            | 说明                                             |
+| ------------------------------ | ------------------- | ------------------------------------------------ |
+| `VITE_DEMO_PROXY_TARGET`       | 调 `/demo` 接口时   | 开发代理目标，如 `http://127.0.0.1:8888`         |
+| `VITE_FEATURE_GIS`             | GIS 项目建议 `true` | 为 `true` 时首页显示 Cesium 入口；`false` 则关闭 |
+| `VITE_CESIUM_ION_ACCESS_TOKEN` | 否                  | 使用 Cesium Ion 资产时填写；默认 OSM 底图可不填  |
+
+**GIS 看不到地图入口？**
+
+1. 确认 `.env` 中有 `VITE_FEATURE_GIS=true`
+2. 重启 `pnpm dev`
+3. 开发环境未配置时也会默认尝试开启 GIS（见 `useFeatureGis`），生产构建仍以 env 为准
+
+---
+
+## 四、本地开发能做什么
+
+启动 `pnpm dev` 后：
+
+| 入口               | 路径（Hash）         | 说明                         |
+| ------------------ | -------------------- | ---------------------------- |
+| 首页               | `/#/`                | 应用壳；开发模式下有示例卡片 |
+| Store / Alert 示例 | `/#/examples/test`   | Pinia、全局 Alert            |
+| Cesium 示例        | `/#/examples/cesium` | 三维地图（需 GIS 开启）      |
+
+`src/views/examples/` 下的页面 **不会打进生产包**（见 `src/router/index.ts`），可放心放演示代码。
+
+---
+
+## 五、目录与路径别名
+
+### 主要目录
+
+```
+src/
+├── views/          # 页面（约定式路由，见下一节）
+├── components/     # 公共组件
+├── layout/         # 布局组件
+├── api/            # 接口请求
+├── stores/         # Pinia
+├── utils/          # 工具、composables、cesium 封装
+├── styles/         # 全局样式（global.css、shell.css）
+├── router/         # 路由入口（一般不用改）
+interface/          # 业务 TS 类型
+types/              # 全局类型、env.d.ts
+docs/               # 文档
+```
+
+### 路径别名（import 时用）
+
+| 别名            | 指向                     |
+| --------------- | ------------------------ |
+| `@/`            | `src/`                   |
+| `@components/`  | `src/components/`        |
+| `@views/`       | `src/views/`             |
+| `@api/`         | `src/api/`               |
+| `@stores/`      | `src/stores/`            |
+| `@utils/`       | `src/utils/`             |
+| `@composables/` | `src/utils/composables/` |
+| `@interface/`   | `interface/`             |
+| `@layout/`      | `src/layout/`            |
+
+示例：
+
+```ts
+import { useCounterStore } from '@stores/useCounter';
+import { useFeatureGis } from '@composables/useFeatureGis';
+import MyCard from '@components/MyCard/index.vue';
+```
+
+---
+
+## 六、约定式路由（重要）
+
+无需手写 `routes` 数组：`src/views` 下每个 `*.vue` 会自动注册。
+
+**规则简述**
+
+- 文件路径 → URL 路径（去掉 `views`、去掉 `/index`）
+- 目录名会转为 **kebab-case**
+
+| 文件                                    | 访问路径                |
+| --------------------------------------- | ----------------------- |
+| `src/views/index.vue`                   | `/#/`                   |
+| `src/views/UserList/index.vue`          | `/#/user-list`          |
+| `src/views/system/RoleManage/index.vue` | `/#/system/role-manage` |
+| `src/views/examples/test/index.vue`     | `/#/examples/test`      |
+
+**新增业务页步骤**
+
+1. 创建 `src/views/YourFeature/index.vue`
+2. 保存后刷新浏览器，直接访问 `/#/your-feature`
+3. 在页面内用 `useRouter()` / `<router-link to="...">` 跳转
+
+```vue
+<!-- src/views/Dashboard/index.vue -->
+<template>
+  <div>业务大屏</div>
+</template>
+```
+
+---
+
+## 七、接口与代理
+
+- 接口代码放在 `src/api/`
+- 开发环境已配置代理：请求 **`/demo`** 会转发到 `VITE_DEMO_PROXY_TARGET`
+
+```ts
+// 示例：axios 请求会走 vite proxy
+// GET http://localhost:3000/demo/xxx  →  VITE_DEMO_PROXY_TARGET/demo/xxx
+```
+
+从 OpenAPI 生成客户端：
+
+```bash
+pnpm gen:api
+```
+
+（具体配置见 `scripts/gen-api.cjs`）
+
+---
+
+## 八、状态与全局能力
+
+- **Pinia**：`src/stores/`，已接入持久化插件
+- **全局 Alert**：`useAlert()`（`@composables/useAlert`）
+- **全局组件**：在 `src/utils/components` 注册
+- **指令**：如 `v-focus`（`src/directive/`）
+
+示例页 `/#/examples/test` 演示了 Store + Alert 的用法。
+
+---
+
+## 九、GIS / Cesium（可选）
+
+启用条件：`package.json` 含 `cesium`，且 `.env` 中 `VITE_FEATURE_GIS=true`（或使用脚手架 `--gis` 创建）。
+
+**在业务页中嵌入地图**
+
+```vue
+<template>
+  <CesiumViewer class="map-host" />
+</template>
+
+<script setup lang="ts">
+import CesiumViewer from '@components/CesiumViewer/index.vue';
+</script>
+
+<style scoped>
+.map-host {
+  width: 100%;
+  height: 480px;
+}
+</style>
+```
+
+**或自行创建 Viewer**
+
+```ts
+import { createViewer, destroyViewer } from '@utils/cesium';
+```
+
+- 默认 **OpenStreetMap** 底图，一般不需要 Ion Token
+- 开发时 Workers/Assets 由 `scripts/vite-plugin-cesium-dev.ts` 提供
+- 生产构建会复制 `dist/cesium/`，`base: './'` 适合静态部署
+
+---
+
+## 十、常用命令
+
+```bash
+pnpm dev            # 开发（端口 3000，自动打开浏览器）
+pnpm build          # 生产构建 → dist/
+pnpm preview        # 本地预览构建结果
+pnpm typecheck      # TypeScript 检查
+pnpm lint:all       # ESLint + Stylelint + Prettier 检查
+pnpm lint:fix       # 自动修复 ESLint
+pnpm test:run       # 单元测试（Vitest）
+pnpm verify         # typecheck + lint（提交前建议）
+```
+
+---
+
+## 十一、构建与部署
+
+```bash
+pnpm build
+```
+
+产物在 `dist/`：
+
+- `index.html`、JS/CSS 在 `assets/`
+- 若启用 GIS，另有 `cesium/` 静态资源目录
+
+部署到任意静态服务器（Nginx、OSS、GitHub Pages 等）即可；注意站点需能访问 **相对路径** 资源（已设置 `base: './'`）。
+
+预览构建：
+
+```bash
+pnpm preview
+```
+
+---
+
+## 十二、推荐日常流程
+
+1. `cp .env.example .env`，按需改代理与 GIS
+2. `pnpm dev`，从首页示例熟悉 Store / 地图
+3. 在 `src/views/` 下新增业务目录
+4. 在 `src/api/`、`src/stores/` 补充接口与状态
+5. 提交前执行 `pnpm verify`
+
+---
+
+## 十三、脚手架创建新项目（摘要）
+
+```bash
+pnpm create swdg-frontend my-app
+cd my-app
+pnpm dev
+```
+
+- 交互默认 **不启用 GIS**；三维项目请选 Y 或加 `--gis`
+- 生成目录含 `docs/ONBOARDING.md`（与本文同步）和 `.swdg/manifest.json`（记录创建选项）
+
+更多参数：`pnpm create swdg-frontend --help` 或根 [README](../README.md)。
+
+---
+
+## 十四、遇到问题
+
+| 现象                   | 处理                                                               |
+| ---------------------- | ------------------------------------------------------------------ |
+| 首页没有 Cesium 卡片   | `.env` 加 `VITE_FEATURE_GIS=true` 并重启 dev                       |
+| 地图白屏 / Worker 报错 | 确认已 `pnpm install`，重启 dev；看控制台是否 404 `cesium/Workers` |
+| 改 env 不生效          | 必须重启 `pnpm dev`                                                |
+| 新页面 404             | 确认文件在 `src/views/` 下且路径符合约定；Hash 地址带 `#`          |
+| TS 路径报错            | 使用 `@/` 等别名，与 `tsconfig.json` 的 `paths` 一致               |
+
+仍无法解决时，把浏览器控制台与终端完整报错发给维护人。

package/template/docs/TESTING.md

@@ -0,0 +1,104 @@
+# 测试与发布门禁
+
+发布 `create-swdg-frontend` / `swdg` 到 npmjs **前必须** 通过完整测试管道（tag 触发 Release 时由 GitHub Actions 执行；本地 `pnpm test: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/package.json

@@ -9,73 +9,80 @@
     "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:run": "vitest run"
+    "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"
     }
   },
-  "lint-staged": {
-    "*.{js,jsx,ts,tsx,vue}": [
-      "eslint --fix",
-      "prettier --write"
-    ],
-    "*.{css,scss,less,html,md,json,yml,yaml}": [
-      "prettier --write"
-    ]
-  },
   "dependencies": {
-    "axios": "^1.13.2",
-    "lint-staged": "^16.2.7",
+    "axios": "^1.16.1",
+    "cesium": "^1.141.0",
     "pinia": "^3.0.4",
     "pinia-plugin-persistedstate": "^4.7.1",
-    "vue": "^3.5.26",
-    "vue-router": "^4.6.4"
+    "vue": "^3.5.34",
+    "vue-router": "^5.0.7"
   },
   "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",
+    "@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.7.0",
-    "fs-extra": "^11.3.3",
+    "eslint-plugin-vue": "^10.9.1",
+    "fs-extra": "^11.3.5",
     "husky": "^9.1.7",
-    "jsdom": "^27.4.0",
-    "less": "^4.5.1",
-    "prettier": "^3.8.0",
+    "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.97.2",
-    "stylelint": "^16.26.1",
+    "sass-embedded": "^1.100.0",
+    "stylelint": "^17.12.0",
     "stylelint-config-recommended-vue": "^1.6.1",
-    "stylelint-config-standard": "^36.0.0",
-    "typescript": "~5.9.3",
+    "stylelint-config-standard": "^40.0.0",
+    "typescript": "~6.0.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"
+    "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"
 }