create-swdg-frontend 0.2.1 → 0.2.2

package/README.md

@@ -1,14 +1,17 @@
 # create-swdg-frontend
 
-从 SWDG 模板生成新项目。npm 包名 **`create-swdg-frontend`**，对应命令：
+从 SWDG 模板生成新项目。
+
+**官方命令：**
 
 ```bash
 pnpm create swdg-frontend my-app
-# 或
-pnpm dlx create-swdg-frontend my-app
 ```
 
-> `pnpm create swdg` 会去找包 `create-swdg`（与本包无关），请使用上面的 `swdg-frontend`。
+| | |
+|---|---|
+| ✅ | `pnpm create swdg-frontend` / `pnpm dlx create-swdg-frontend` |
+| ❌ | `pnpm create swdg`（会解析为不存在的 npm 包 `create-swdg`） |
 
 ### 常用参数
 

package/lib/constants.js

@@ -6,7 +6,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 export const PACKAGE_ROOT = path.resolve(__dirname, '..');
 export const TEMPLATE_DIR = path.join(PACKAGE_ROOT, 'template');
 export const STUBS_DIR = path.join(PACKAGE_ROOT, 'stubs');
-export const SCAFFOLD_VERSION = '0.2.1';
+export const SCAFFOLD_VERSION = '0.2.2';
 
 /** 可选特性：重型依赖默认关闭，创建时 opt-in */
 export const FEATURES = {

package/lib/gis.js

@@ -86,6 +86,8 @@ export async function removeGisIntegration(destDir) {
     await removePathIfExists(destDir, relativePath);
   }
   await patchPackageWithoutGis(destDir);
+  // package.json 已去掉 cesium 等依赖，旧 lockfile 会导致 pnpm frozen install 失败
+  await fs.rm(path.join(destDir, 'pnpm-lock.yaml'), { force: true });
   await patchReadmeWithoutGis(destDir);
   await applyNoGisStubs(destDir);
   await upsertEnvFeature(destDir, false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-swdg-frontend",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Scaffold a new SWDG frontend project",
   "type": "module",
   "bin": {

package/template/README.md

@@ -32,12 +32,18 @@ pnpm dev               # http://localhost:3000 ，改 .env 后需重启
 
 ## 创建新项目（脚手架）
 
+**官方命令（请只用这一条）：**
+
 ```bash
 pnpm create swdg-frontend my-app
-# 或
-npx create-swdg-frontend my-app
 ```
 
+| 命令 | 说明 |
+|------|------|
+| `pnpm create swdg-frontend my-app` | ✅ 正确，对应 npm 包 `create-swdg-frontend` |
+| `npx create-swdg-frontend my-app` | ✅ 同上 |
+| `pnpm create swdg my-app` | ❌ 会去找不存在的包 `create-swdg`，不要用 |
+
 交互会询问：项目名、**是否 GIS（默认否）**、是否安装依赖、是否 Git、是否 typecheck 校验。
 
 ```bash

package/template/docs/MAINTAINER.md

@@ -34,7 +34,9 @@ frontend-framework/     # 模板源仓库（本仓库）
 # 1. 提交并推到 GitHub（main 上 CI 会跑 test:ci）
 git push github main
 
-# 2. 打 tag 并推送（版本号与 tag 一致，格式 vX.Y.Z；Release workflow 会再跑 test:ci 后 publish）
+# 2. 打 tag 并推送（版本号与 tag 一致，格式 vX.Y.Z；Release workflow 会跑 test:ci 后 publish）
+
+用户创建项目请统一文档为：`pnpm create swdg-frontend <name>`（不要用 `pnpm create swdg`）。
 git tag v0.2.1
 git push github v0.2.1
 ```

package/template/docs/ONBOARDING.md

@@ -82,7 +82,7 @@ src/
 ├── api/            # 接口请求
 ├── stores/         # Pinia
 ├── utils/          # 工具、composables、cesium 封装
-├── styles/         # 全局样式（global.css、shell.css）
+├── styles/         # tokens / global / responsive / shell / alerts
 ├── router/         # 路由入口（一般不用改）
 interface/          # 业务 TS 类型
 types/              # 全局类型、env.d.ts
@@ -111,6 +111,24 @@ import { useFeatureGis } from '@composables/useFeatureGis';
 import MyCard from '@components/MyCard/index.vue';
 ```
 
+### 样式与自适应（推荐做法）
+
+模板 **不默认引入** Tailwind 或重型 UI 库，布局用 **原生 CSS**（成熟、无运行时）：
+
+| 文件 | 作用 |
+| ---- | ---- |
+| `tokens.css` | 断点变量、`clamp()` 间距与字号 |
+| `responsive.css` | 遗留工具类 `.grid-h-*` 的响应式列数 |
+| `shell.css` | 首页壳层、`repeat(auto-fill, minmax(...))` 卡片网格 |
+
+断点与业界常用值对齐：**640 / 768 / 1024 / 1280 px**。新页面优先：
+
+- `clamp()` / `min()` / `%` 做流体尺寸
+- **CSS Grid** `auto-fill` + `minmax()` 做卡片列表
+- 需要组件级适配时再用 `@media`，一般不必为自适应单独加 npm 包
+
+若团队已标准化 **Element Plus / Ant Design Vue**，可在业务仓库自行安装；本模板保持样式中立。
+
 ---
 
 ## 六、约定式路由（重要）

package/template/docs/TESTING.md

@@ -8,19 +8,22 @@
 | -------------------- | --------------------------------------- | ----------------- |
 | `pnpm verify`        | typecheck + eslint                      | 日常提交前        |
 | `pnpm test:unit`     | Vitest 单元测试                         | 开发中            |
-| `pnpm test:scaffold` | 脚手架集成（无 install）                | 改 create-swdg 后 |
+| `pnpm test:scaffold` | 脚手架集成（含 --no-gis 生成项目 build）  | 改 create-swdg 后 |
 | `pnpm test:template` | sync + template install/typecheck/build | 改模板后          |
-| **`pnpm test:ci`**   | **完整发布门禁（四阶段）**              | **PR / 发布前**   |
+| `pnpm test:pack`     | npm pack 后从 tarball 跑 CLI 并 build     | 改发布物前        |
+| **`pnpm test:ci`**   | **完整发布门禁（五阶段）**              | **PR / tag 发布** |
 
 ## 发布门禁管道（`pnpm test:ci`）
 
 顺序固定，任一失败即 `exit 1`：
 
 ```
+0. sync        生成 create-swdg/template
 1. verify      根项目 typecheck + eslint
 2. unit        vitest 单元测试
-3. scaffold    --no-gis / --gis 产物、manifest、CLI  smoke
-4. template    sync-template → template 目录 install → typecheck → build
+3. scaffold    产物/manifest/CLI + --no-gis 项目 install/build
+4. template    template install → typecheck → build（GIS on）
+5. pack        npm pack → 从 tarball 创建无 GIS 项目并 build
 ```
 
 `pnpm release x.y.z` 会在改版本号、打 npm 包 **之前** 自动执行 `test:ci`。
@@ -59,6 +62,20 @@
 - 合法参数能退出 0
 - 非法项目名退出非 0
 
+**--no-gis 构建**
+
+- 生成项目 `pnpm install` → `typecheck` → `build` 通过（无 Cesium）
+
+## 发布物测试（pack）
+
+`scripts/test-pack.mjs`：
+
+1. 在 `create-swdg/` 执行 `npm pack`
+2. 从 tarball 安装并运行 CLI（`--no-gis`）
+3. 生成项目 `install` + `typecheck` + `build`
+
+模拟用户 `pnpm create swdg-frontend` 拿到的 npm 包内容。
+
 ## 模板测试（template）
 
 `scripts/test-template.mjs`：
@@ -98,7 +115,8 @@ pnpm release 0.2.1
 | 失败阶段 | 常见原因                                         |
 | -------- | ------------------------------------------------ |
 | verify   | TS 错误、ESLint、单元测试红                      |
-| scaffold | GIS 剥离不完整、manifest 版本与 constants 不一致 |
+| scaffold | GIS 剥离不完整、无 GIS 项目 build 失败          |
 | template | 未 sync、template build 失败（Cesium/路由等）    |
+| pack       | tarball 缺 template、packed CLI 行为异常      |
 
 template 阶段最慢（install + build），本地可先 `pnpm test:scaffold` 快速迭代脚手架逻辑。

package/template/package.json

@@ -22,6 +22,7 @@
     "test:unit": "vitest run",
     "test:run": "vitest run",
     "test:scaffold": "node scripts/test-scaffold.mjs",
+    "test:pack": "node scripts/test-pack.mjs",
     "test:template": "node scripts/test-template.mjs",
     "test:ci": "node scripts/test-pipeline.mjs",
     "verify": "node scripts/verify.mjs"
@@ -64,11 +65,9 @@
     "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",