create-swdg-frontend 0.2.0 → 0.2.2

package/README.md

@@ -1,15 +1,18 @@
 # create-swdg-frontend
 
-从 SWDG 模板生成新项目。CLI 仅负责拷贝与 **feature flags** 裁剪；业务约定在 `template/` 内维护。
+从 SWDG 模板生成新项目。
 
-## 使用
+**官方命令：**
 
 ```bash
-pnpm create swdg my-app
-# 或
-pnpm dlx create-swdg-frontend my-app
+pnpm create swdg-frontend my-app
 ```
 
+| | |
+|---|---|
+| ✅ | `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.0';
+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.0",
+  "version": "0.2.2",
   "description": "Scaffold a new SWDG frontend project",
   "type": "module",
   "bin": {

package/template/README.md

@@ -32,20 +32,26 @@ pnpm dev               # http://localhost:3000 ，改 .env 后需重启
 
 ## 创建新项目（脚手架）
 
+**官方命令（请只用这一条）：**
+
 ```bash
-pnpm create swdg my-app
-# 或
-npx create-swdg-frontend my-app
+pnpm 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
 # 非 GIS 项目（推荐多数后台类应用）
-pnpm create swdg my-app --no-gis --install
+pnpm create swdg-frontend my-app --no-gis --install
 
 # GIS 项目
-pnpm create swdg my-app --gis --install
+pnpm create swdg-frontend my-app --gis --install
 ```
 
 ## 目录结构

package/template/docs/MAINTAINER.md

@@ -6,7 +6,7 @@
 
 ```
 frontend-framework/     # 模板源仓库（本仓库）
-├── create-swdg/        # npm 包 create-swdg-frontend
+├── create-swdg/        # npm 包 create-swdg-frontend（pnpm create swdg-frontend）
 │   ├── bin/index.js    # CLI 入口
 │   ├── lib/            # 提示、特性剥离、manifest
 │   ├── stubs/          # 无 GIS 时的配置替身
@@ -23,22 +23,22 @@ frontend-framework/     # 模板源仓库（本仓库）
 1. 登录 [npmjs.com](https://www.npmjs.com/)，确认账号已验证邮箱  
 2. 确认包名 **`create-swdg-frontend`**、**`swdg`** 在你账号下（首次需未被占用）  
 3. npm → Access Tokens → **Generate New Token**  
-   - 类型：**Granular**（Publish 权限）或 **Classic**（Automation）  
-4. GitHub 仓库 [Inupedia/swdg-frontend](https://github.com/Inupedia/swdg-frontend) → **Settings → Secrets and variables → Actions**  
-5. 新建 Secret：`NPM_TOKEN` = 上一步的 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. 本地确认测试通过
-pnpm test:ci
-
-# 2. 提交并推到 GitHub（如有未 push 的改动）
+# 1. 提交并推到 GitHub（main 上 CI 会跑 test:ci）
 git push github main
 
-# 3. 打 tag 并推送（版本号与 tag 一致，格式 vX.Y.Z）
-git tag v0.2.0
-git push github v0.2.0
+# 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
 ```
 
 4. 打开 **Actions → Release to npm**，等待 workflow 完成  
@@ -50,7 +50,7 @@ CI 会：从 tag 解析版本 → `test:ci` → 发布 `create-swdg-frontend`
 
 ```bash
 pnpm test:ci
-pnpm release 0.2.0
+pnpm release 0.2.1
 ```
 
 详见 [TESTING.md](./TESTING.md)。

package/template/docs/ONBOARDING.md

@@ -9,7 +9,7 @@
 | 方式               | 适合谁                           | 第一步                                                       |
 | ------------------ | -------------------------------- | ------------------------------------------------------------ |
 | **直接使用本仓库** | 团队统一模板、在 monorepo 上迭代 | `git clone` → `pnpm install`                                 |
-| **脚手架新建项目** | 每个业务一条独立仓库             | `pnpm create swdg my-app`（见根目录 [README](../README.md)） |
+| **脚手架新建项目** | 每个业务一条独立仓库             | `pnpm create swdg-frontend my-app`（见根目录 [README](../README.md)） |
 
 两种方式的项目结构、命令、路由约定 **一致**；脚手架可通过 `--gis` / `--no-gis` 裁剪 Cesium 相关文件。
 
@@ -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**，可在业务仓库自行安装；本模板保持样式中立。
+
 ---
 
 ## 六、约定式路由（重要）
@@ -259,7 +277,7 @@ pnpm preview
 ## 十三、脚手架创建新项目（摘要）
 
 ```bash
-pnpm create swdg my-app
+pnpm create swdg-frontend my-app
 cd my-app
 pnpm dev
 ```
@@ -267,7 +285,7 @@ pnpm dev
 - 交互默认 **不启用 GIS**；三维项目请选 Y 或加 `--gis`
 - 生成目录含 `docs/ONBOARDING.md`（与本文同步）和 `.swdg/manifest.json`（记录创建选项）
 
-更多参数：`create-swdg` 包内 `pnpm create swdg --help` 或根 [README](../README.md)。
+更多参数：`pnpm create swdg-frontend --help` 或根 [README](../README.md)。
 
 ---
 

package/template/docs/TESTING.md

@@ -1,6 +1,6 @@
 # 测试与发布门禁
 
-发布 `create-swdg-frontend` / `swdg` 到 npmjs **前必须** 通过完整测试管道。本地与 CI 使用同一套命令。
+发布 `create-swdg-frontend` / `swdg` 到 npmjs **前必须** 通过完整测试管道（tag 触发 Release 时由 GitHub Actions 执行；本地 `pnpm test:ci` 可选）。
 
 ## 命令一览
 
@@ -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",