create-component-template-cli 1.0.0 → 1.0.2

package/docs/2026-05-11T10-04-44-/344/270/211/345/245/227/346/250/241/346/235/277/351/207/215/346/236/204/2026-05-11T10-04-44-/344/270/211/345/245/227/346/250/241/346/235/277/351/207/215/346/236/204-/350/256/276/350/256/241/346/226/271/346/241/210.md

@@ -0,0 +1,477 @@
+# 三套业务模板与两套 Vue 语法风格并存设计方案
+
+## 1. 背景
+
+当前项目里存在两个容易混淆的概念：
+
+1. 业务模板类型
+   表示要生成哪一类业务组件骨架。
+
+2. Vue 语法风格
+   只表示 `index.vue` 使用哪种 Vue 写法。
+
+这次需求已经明确：
+
+- 业务层面的 `templateType` 一共有三种：
+  - `general`
+  - `single-pick`
+  - `multiple-pick`
+- 当前逻辑中的 `setup` 和 `normal` 仍然保留
+- `setup/normal` 只用于决定 `index.vue` 的 Vue 模板写法
+
+因此，这次设计的核心是把“业务模板类型”和“Vue 语法风格”拆成两个独立维度，而不是让 `templateType` 同时承担两种含义。
+
+## 2. 目标
+
+### 2.1 功能目标
+
+1. 支持三种业务模板类型
+2. 保留两种 Vue 语法风格
+3. 支持任意业务模板类型与任意 Vue 语法风格组合使用
+4. 保持现有输出目录结构不变
+5. 最终生成的组件文件名保持稳定
+
+### 2.2 设计目标
+
+1. 参数语义清晰
+2. 模板目录结构清晰
+3. 生成逻辑采用配置驱动
+4. 交互模式与非交互模式规则一致
+
+## 3. 需求拆解
+
+这次需求不是“三套模板替换两套模板”，而是“两层模板选择并存”。
+
+### 3.1 第一层：业务模板类型
+
+这一层决定整套生成内容的业务语义：
+
+- `general`：通用业务模板
+- `single-pick`：产品组单选业务模板
+- `multiple-pick`：产品组多选业务模板
+
+这一层会影响的文件不只有 `index.vue`，还可能包括：
+
+- `typing.ts`
+- `hook.ts`
+- `data.ts`
+- `index.scss`
+- `index.ts`
+
+### 3.2 第二层：Vue 语法风格
+
+这一层只决定 `index.vue` 使用哪种 Vue 写法：
+
+- `setup`：`<script setup>`
+- `normal`：`defineComponent`
+
+最终允许的组合关系应为：
+
+- `general + setup`
+- `general + normal`
+- `single-pick + setup`
+- `single-pick + normal`
+- `multiple-pick + setup`
+- `multiple-pick + normal`
+
+## 4. 现状分析
+
+### 4.1 当前实现特点
+
+当前实现里：
+
+1. `templateType` 只有 `setup` 和 `normal`
+2. 实际上只有 `index.vue` 会根据 `templateType` 切换模板文件
+3. 其他文件模板都是固定的
+
+这说明当前架构本质上只支持：
+
+- 单一业务模板
+- 两种 Vue 语法风格
+
+### 4.2 当前问题
+
+1. `templateType` 语义混乱
+   它现在承载的是 Vue 写法选择，而不是业务模板选择。
+
+2. 缺少业务模板层
+   目前没有一个明确维度控制 `general`、`single-pick`、`multiple-pick`。
+
+3. 模板组织方式扩展性不足
+   如果继续在平铺目录上叠加判断，后续文件差异会越来越难维护。
+
+## 5. 重构原则
+
+### 5.1 两个维度必须拆开
+
+业务模板类型和 Vue 语法风格属于不同维度，不能再复用同一个参数语义。
+
+### 5.2 业务模板决定整套模板目录
+
+每种业务模板对应一套独立模板资源。
+
+### 5.3 Vue 风格只决定 `index.vue`
+
+`setup/normal` 只影响 `index.vue` 模板文件选择，不影响其他文件来源。
+
+### 5.4 模板源文件名与最终输出文件名分离
+
+内部可以通过不同模板源文件区分 Vue 写法，但最终输出给组件目录的文件名必须统一。
+
+## 6. 参数设计
+
+建议把参数拆成两个：
+
+### 6.1 `templateType`
+
+表示业务模板类型：
+
+- `general`
+- `single-pick`
+- `multiple-pick`
+
+### 6.2 `vueTemplateType`
+
+表示 Vue 语法风格：
+
+- `setup`
+- `normal`
+
+如果暂时不想新增参数名，也可以过渡为：
+
+- `templateType`：业务模板类型
+- `vueStyle`：Vue 语法风格
+
+本方案更推荐使用语义更明确的命名，例如 `vueTemplateType`。
+
+## 7. 目录设计
+
+建议模板目录按业务模板类型分组，在每个业务模板目录中，仅对 `index.vue` 的模板源文件再区分两种 Vue 写法。
+
+```txt
+plop-templates/
+  general/
+    index.setup.vue.hbs
+    index.normal.vue.hbs
+    typing.ts.hbs
+    hook.ts.hbs
+    data.ts.hbs
+    index.scss.hbs
+    index.ts.hbs
+  single-pick/
+    index.setup.vue.hbs
+    index.normal.vue.hbs
+    typing.ts.hbs
+    hook.ts.hbs
+    data.ts.hbs
+    index.scss.hbs
+    index.ts.hbs
+  multiple-pick/
+    index.setup.vue.hbs
+    index.normal.vue.hbs
+    typing.ts.hbs
+    hook.ts.hbs
+    data.ts.hbs
+    index.scss.hbs
+    index.ts.hbs
+```
+
+### 7.1 输出文件命名规则
+
+这里必须严格区分“模板源文件名”和“最终生成文件名”：
+
+1. 模板源文件名
+   内部允许使用：
+   - `index.setup.vue.hbs`
+   - `index.normal.vue.hbs`
+
+2. 最终生成文件名
+   无论选择哪种 Vue 风格，最终都只生成：
+   - `src/index.vue`
+
+也就是说，`setup/normal` 只参与模板选择，不进入最终产物文件名。
+
+### 7.2 这样设计的原因
+
+1. 在算什么
+   这里算的是“如何让模板选择逻辑可区分，同时保持最终产物结构稳定”。
+
+2. 为什么这么算
+   因为 `setup/normal` 只是模板来源差异，不是最终组件目录结构差异。对使用方来说，组件入口文件始终应该是统一的 `index.vue`。
+
+3. 好处
+   后续如果新增业务模板，只需要新增一个目录；如果新增新的 Vue 风格，只需要在各业务目录下补充对应的 `index.xxx.vue.hbs`。
+
+## 8. 配置结构设计
+
+建议抽离两套配置。
+
+### 8.1 业务模板注册表
+
+```js
+BUSINESS_TEMPLATE_MAP = {
+  general: {
+    label: '通用模板',
+    templateDir: 'general'
+  },
+  'single-pick': {
+    label: '产品组单选模板',
+    templateDir: 'single-pick'
+  },
+  'multiple-pick': {
+    label: '产品组多选模板',
+    templateDir: 'multiple-pick'
+  }
+}
+```
+
+### 8.2 Vue 风格注册表
+
+```js
+VUE_TEMPLATE_STYLE_MAP = {
+  setup: {
+    label: 'script setup 风格',
+    vueTemplateFile: 'index.setup.vue.hbs'
+  },
+  normal: {
+    label: 'defineComponent 风格',
+    vueTemplateFile: 'index.normal.vue.hbs'
+  }
+}
+```
+
+### 8.3 固定输出文件清单
+
+```js
+TEMPLATE_FILES = [
+  { output: 'src/index.vue', type: 'vue-entry' },
+  { output: 'src/index.scss', template: 'index.scss.hbs' },
+  { output: 'src/typing.ts', template: 'typing.ts.hbs' },
+  { output: 'src/hook.ts', template: 'hook.ts.hbs' },
+  { output: 'src/data.ts', template: 'data.ts.hbs' },
+  { output: 'index.ts', template: 'index.ts.hbs' }
+]
+```
+
+## 9. 模板选择逻辑
+
+### 9.1 选择流程
+
+1. 先根据 `templateType` 选择业务模板目录
+2. 再根据 `vueTemplateType` 选择 `index.vue` 对应模板源文件
+3. 将选中的 Vue 模板源文件渲染后统一写入 `src/index.vue`
+4. 其他文件全部从业务模板目录读取固定模板
+
+### 9.2 伪代码
+
+```js
+读取 templateType
+读取 vueTemplateType
+
+校验 templateType 是否合法
+校验 vueTemplateType 是否合法
+
+businessDir = BUSINESS_TEMPLATE_MAP[templateType].templateDir
+vueFile = VUE_TEMPLATE_STYLE_MAP[vueTemplateType].vueTemplateFile
+
+for 每个输出文件:
+  if 当前文件是 index.vue:
+    templatePath = businessDir + vueFile
+    outputPath = src/index.vue
+  else:
+    templatePath = businessDir + 固定模板文件名
+    outputPath = 固定输出路径
+
+  读取模板
+  渲染变量
+  写入 outputPath
+```
+
+## 10. 代码改造方案
+
+### 10.1 `src/generate.mjs`
+
+#### 改造目标
+
+让生成器同时接收“业务模板类型”和“Vue 风格”两个参数。
+
+#### 改造内容
+
+1. 新增业务模板合法值校验
+2. 新增 Vue 风格合法值校验
+3. 把 `index.vue` 模板选择逻辑改成二段式选择
+4. 选中的 Vue 模板源文件最终统一输出为 `src/index.vue`
+5. 其他模板文件按业务模板目录读取
+
+### 10.2 `plopfile.mjs`
+
+#### 改造目标
+
+交互模式中要让用户先后选择两个维度。
+
+#### 改造内容
+
+1. 增加业务模板选择项
+2. 保留 Vue 风格选择项
+3. 生成动作时同时带上两个参数
+4. 模板路径拼接逻辑改为“业务目录 + Vue 风格文件名”
+5. 最终输出路径始终保持 `src/index.vue`
+
+### 10.3 `bin/cli.mjs`
+
+#### 改造目标
+
+CLI 参数说明与帮助文案反映双维度结构。
+
+#### 改造内容
+
+1. `--templateType` 改为说明业务模板类型
+2. 新增 Vue 风格参数说明
+3. 明确说明 `setup/normal` 不会改变最终输出文件名
+4. 示例命令补充若干典型组合
+
+### 10.4 文档同步
+
+需要同步更新：
+
+- `README.md`
+- `AGENTS.md`
+- `CLAUDE.md`
+
+避免后续使用者继续把 `templateType` 理解成 Vue 写法开关。
+
+## 11. 模板内容设计
+
+### 11.1 `general`
+
+用途：通用业务组件骨架。
+
+设计原则：
+
+- 参考现有模板内容
+- 去掉单选、多选场景的强业务耦合
+- 保留基础 props、hook、data 占位
+
+### 11.2 `single-pick`
+
+用途：产品组单选业务模板。
+
+设计原则：
+
+- 参考现有 `SinglePickButtonGroup` 相关痕迹
+- `typing.ts` 预置单选值结构
+- `data.ts` 预置单选项数组结构
+
+### 11.3 `multiple-pick`
+
+用途：产品组多选业务模板。
+
+设计原则：
+
+- 在单选模板思路基础上扩展为多选语义
+- `typing.ts` 预置多选值结构
+- `data.ts` 预置多选项数组结构
+
+### 11.4 关于 `index.vue`
+
+每个业务模板都提供两份 `index.vue` 模板源文件：
+
+- `index.setup.vue.hbs`
+- `index.normal.vue.hbs`
+
+它们表达的是同一业务模板下的两种 Vue 书写方式，不是两类业务模板。
+最终落地生成时，文件名始终统一为 `index.vue`。
+
+## 12. 兼容性策略
+
+### 12.1 旧参数兼容问题
+
+当前实现中 `templateType` 还承担 Vue 风格含义，因此重构后存在迁移问题。
+
+### 12.2 建议过渡方案
+
+建议采用过渡兼容：
+
+1. 新版本引入双参数模型
+2. 若用户仍传旧的 `templateType=setup|normal`
+   则提示参数语义已调整
+3. 过渡期内可将旧值映射为：
+   - 业务模板默认 `general`
+   - Vue 风格使用旧值
+
+### 12.3 过渡映射示意
+
+```txt
+旧输入:
+--templateType=setup
+
+过渡解释:
+templateType = general
+vueTemplateType = setup
+```
+
+这样做的原因是：
+
+1. 在算什么
+   这里算的是“如何减少旧脚本失效风险”。
+
+2. 为什么这么算
+   因为旧值本来就只表达 Vue 风格，并不表达业务模板，所以映射到默认业务模板 `general` 最符合原始语义。
+
+## 13. 测试与验证方案
+
+### 13.1 组合验证
+
+至少验证以下 6 组：
+
+1. `general + setup`
+2. `general + normal`
+3. `single-pick + setup`
+4. `single-pick + normal`
+5. `multiple-pick + setup`
+6. `multiple-pick + normal`
+
+### 13.2 异常验证
+
+1. 非法 `templateType` 报错
+2. 非法 `vueTemplateType` 报错
+3. 未传业务模板时默认值正确
+4. 未传 Vue 风格时默认值正确
+5. `overwrite` / `skip` 行为保持不变
+
+### 13.3 输出验证
+
+重点检查：
+
+1. 目录结构是否正确
+2. 六个目标文件是否完整生成
+3. `index.vue` 是否真的对应到所选 Vue 风格
+4. 其他文件是否真的来自所选业务模板
+5. 最终输出文件名是否始终为 `index.vue`
+
+## 14. 实施步骤
+
+1. 修正模板参数设计
+2. 新建三套业务模板目录
+3. 每套业务模板补齐两份 `index.vue` 模板源文件
+4. 复制并改造 `typing.ts`、`hook.ts`、`data.ts` 等文件模板
+5. 重构 `src/generate.mjs`
+6. 重构 `plopfile.mjs`
+7. 更新 `bin/cli.mjs` 帮助文案
+8. 更新仓库说明文档
+9. 执行 6 组组合命令做闭环验证
+10. 验证最终是否始终输出统一文件名 `index.vue`
+11. 产出实施总结文档
+
+## 15. 结论
+
+推荐采用“业务模板类型 + Vue 语法风格”双维度方案。
+
+其中：
+
+- `templateType` 只负责业务模板语义
+- `setup/normal` 只负责 `index.vue` 的 Vue 书写风格
+- `index.setup.vue.hbs` / `index.normal.vue.hbs` 只是模板源文件名
+- 最终生成文件名始终统一为 `index.vue`
+
+这样既符合你的补充定义，也能最大程度复用现有逻辑，并为后续继续扩展业务模板留下稳定结构。

package/docs/2026-05-11T12-35-00-npx/346/211/247/350/241/214/345/205/245/345/217/243/344/277/256/345/244/215/2026-05-11T12-35-00-npx/346/211/247/350/241/214/345/205/245/345/217/243/344/277/256/345/244/215-/345/256/236/346/226/275/346/226/271/346/241/210.md

@@ -0,0 +1,66 @@
+# npx 执行入口修复-实施方案
+
+## 1. 问题描述
+
+用户在发包成功后执行 `npx create-component-template-cli`，终端报错：
+
+```text
+'cvct' 不是内部或外部命令，也不是可运行的程序或批处理文件。
+```
+
+但执行 `npx cvct` 可以正常输出版本号。
+
+## 2. 原因分析
+
+当前包的 `package.json` 只声明了一个可执行入口：
+
+```text
+bin:
+  cvct -> bin/cli.mjs
+```
+
+这会导致：
+
+1. 用户如果明确执行 `npx cvct`，npm 能找到对应的可执行文件。
+2. 用户如果执行 `npx create-component-template-cli`，npm 在 Windows 环境下不会自动把包名映射成 `cvct`，从而出现命令不存在。
+
+## 3. 实施方案
+
+### 3.1 修复入口映射
+
+在 `package.json` 中同时声明两个可执行名称，并都指向同一个入口文件：
+
+```text
+bin:
+  cvct -> bin/cli.mjs
+  create-component-template-cli -> bin/cli.mjs
+```
+
+### 3.2 更新使用文档
+
+在 README 中明确说明两种推荐调用方式：
+
+```text
+npx create-component-template-cli
+npx cvct
+```
+
+这样做的原因是：
+
+1. 包名调用方式更符合用户直觉。
+2. 短命令调用方式更适合高频使用。
+
+## 4. 验证方案
+
+使用以下命令做闭环验证：
+
+```text
+步骤 1：验证本地入口文件仍可正常输出版本
+步骤 2：验证 npx cvct --version 可以执行
+步骤 3：验证 npx create-component-template-cli --version 可以执行
+步骤 4：验证 npm pack 后产物包含 bin/cli.mjs 与双 bin 映射
+```
+
+## 5. 风险说明
+
+本次修改只涉及包元数据与说明文档，不改变模板生成逻辑，业务风险较低。

package/docs/2026-05-11T12-35-00-npx/346/211/247/350/241/214/345/205/245/345/217/243/344/277/256/345/244/215/2026-05-11T12-35-00-npx/346/211/247/350/241/214/345/205/245/345/217/243/344/277/256/345/244/215-/346/200/235/350/267/257/346/226/207/346/241/243.md

@@ -0,0 +1,69 @@
+# npx 执行入口修复-思路文档
+
+## 1. 排查思路
+
+这次问题表面上看是“命令找不到”，但需要先区分是以下哪一层出了问题：
+
+1. 包没有成功发布。
+2. 发布包里缺少 `bin/cli.mjs`。
+3. `package.json` 的 `bin` 字段配置错误。
+4. `npx` 调用的命令名和实际暴露的 bin 名不一致。
+
+## 2. 实际排查过程
+
+### 2.1 先看本地源码
+
+确认 `package.json` 中存在：
+
+```text
+name = create-component-template-cli
+bin.cvct = bin/cli.mjs
+```
+
+说明源码只暴露了 `cvct` 这个命令。
+
+### 2.2 再看打包产物
+
+通过 `npm pack` 检查 tarball 内容，确认 `bin/cli.mjs` 已被打进包里。
+
+这一步的意义是：
+
+1. 排除“发包漏文件”。
+2. 证明运行时报错不是因为入口脚本缺失。
+
+### 2.3 再看线上元数据
+
+通过 `npm view create-component-template-cli ...` 查看线上元数据，确认线上 `bin` 仍然只有 `cvct`。
+
+### 2.4 最后做最小复现
+
+复现结果：
+
+```text
+npx cvct --version                           -> 成功
+npx create-component-template-cli --version -> 失败
+```
+
+这说明真正的问题不是 CLI 代码本身，而是可执行命令别名不完整。
+
+## 3. 为什么这样修
+
+最小改动方案是直接补一个与包名同名的 bin 映射，而不是改动 `bin/cli.mjs` 的执行逻辑。
+
+原因：
+
+1. 问题发生在 npm 命令解析阶段，不在业务代码阶段。
+2. 增加包名别名不会影响已有用户继续使用 `cvct`。
+3. 兼容“记包名”和“记短命令”两类用户习惯。
+
+## 4. 伪代码示意
+
+```text
+if user_run_by_package_name:
+  resolve bin["create-component-template-cli"]
+
+if user_run_by_short_name:
+  resolve bin["cvct"]
+
+both -> execute "bin/cli.mjs"
+```

package/docs/2026-05-11T12-35-00-npx/346/211/247/350/241/214/345/205/245/345/217/243/344/277/256/345/244/215/2026-05-11T12-35-00-npx/346/211/247/350/241/214/345/205/245/345/217/243/344/277/256/345/244/215-/346/200/273/347/273/223/346/226/207/346/241/243.md

@@ -0,0 +1,27 @@
+# npx 执行入口修复-总结文档
+
+## 本次完成内容
+
+1. 定位了 `npx create-component-template-cli` 报错的根因。
+2. 在 `package.json` 中新增了 `create-component-template-cli -> bin/cli.mjs` 的 bin 映射。
+3. 保留了原有 `cvct -> bin/cli.mjs` 的短命令入口，避免兼容性回退。
+4. 重写 README 的使用说明，补充了包名调用方式与短命令调用方式。
+5. 完成了本地命令验证与打包产物验证。
+
+## 当前版本收益
+
+1. 用户可以直接执行 `npx create-component-template-cli`，调用方式和包名保持一致。
+2. 老用户仍可继续执行 `npx cvct`，不会受到影响。
+3. 文档说明更完整，后续排障成本更低。
+
+## 目前不足
+
+1. README 之外的其他文档（如 AGENTS/CLAUDE 中的示例）仍以本地 `node bin/cli.mjs` 为主，没有单独强调包名执行方式。
+2. 仓库当前没有自动化测试覆盖“npx/发布后入口解析”这个场景，未来仍可能出现回归。
+3. 打包产物目前包含较多与发布无关的文件，后续可以考虑通过 `files` 字段进一步收敛 npm 包体积。
+
+## 后续建议
+
+1. 发一个补丁版本，把新的 bin 映射发布到 npm。
+2. 增加一个发布前校验脚本，自动验证 tarball 中的 `bin` 配置和入口文件是否完整。
+3. 视情况补充 `files` 字段，减少无关文件进入 npm 包。

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "create-component-template-cli",
-  "description": "create-vue-component-template,A CLI tool for creating standardized Vue 3 + TypeScript + Sass public component templates.",
-  "version": "1.0.0",
+  "description": "create-vue-component-template-cli,A CLI tool for creating standardized Vue 3 + TypeScript + Sass public component templates.",
+  "version": "1.0.2",
   "type": "module",
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "cvct": "bin/cli.mjs"
+    "cctc": "bin/cli.mjs",
+    "create-component-template-cli": "bin/cli.mjs"
   },
   "access": "public",
   "dependencies": {

package/plop-templates/general/data.ts.hbs

@@ -0,0 +1,16 @@
+import type { DataType } from './typing'
+
+const data: Array<DataType> = [
+  {
+    label: '示例项1',
+    value: 'option-1',
+  },
+  {
+    label: '示例项2',
+    value: 'option-2',
+  },
+]
+
+export {
+  data,
+}

package/plop-templates/general/hook.ts.hbs

@@ -0,0 +1,11 @@
+import { ref } from 'vue'
+import type { {{ componentName }}Props } from './typing'
+
+export const use{{ componentName }} = (props: {{ componentName }}Props) => {
+  const visible = ref(true)
+
+  return {
+    props,
+    visible,
+  }
+}