create-component-template-cli 1.0.0 → 1.0.1

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/package.json

@@ -1,7 +1,7 @@
 {
   "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",
+  "version": "1.0.1",
   "type": "module",
   "publishConfig": {
     "access": "public"

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,
+  }
+}

package/plop-templates/general/index.normal.vue.hbs

@@ -0,0 +1,28 @@
+<template>
+  <div class="{{ class }}"></div>
+</template>
+
+<script lang="ts">
+import { defineComponent, PropType } from 'vue'
+import { {{ componentName }}Props } from './typing'
+import { use{{ componentName }} } from './hook'
+
+export default defineComponent({
+  name: '{{ componentName }}',
+  props: {
+    user: {
+      type: Object as PropType<{{ componentName }}Props['user']>,
+      required: false,
+    },
+  },
+  setup(props) {
+    const {} = use{{ componentName }}(props as {{ componentName }}Props)
+
+    return {}
+  },
+})
+</script>
+
+<style lang="scss" scoped>
+@import './index.scss';
+</style>

package/plop-templates/general/index.scss.hbs

@@ -0,0 +1,5 @@
+.{{class}} {
+  position: absolute;
+  top: 0;
+  left: 0;
+}

package/plop-templates/general/index.setup.vue.hbs

@@ -0,0 +1,20 @@
+<template>
+  <div class="{{ class }}"></div>
+</template>
+
+<script setup lang="ts">
+import { {{ componentName }}Props } from './typing'
+import { use{{ componentName }} } from './hook'
+
+defineOptions({
+  name: '{{ componentName }}',
+})
+
+const props = defineProps<{{ componentName }}Props>()
+
+const {} = use{{ componentName }}(props)
+</script>
+
+<style lang="scss" scoped>
+@import './index.scss';
+</style>

package/plop-templates/{index.ts.hbs → general/index.ts.hbs}

@@ -1,3 +1,4 @@
 import {{ componentName }} from './src/index.vue'
+
 export default {{ componentName }}
-export * from './src/typing'
+export * from './src/typing'

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

@@ -0,0 +1,13 @@
+export enum {{ interfaceName }}Enum {
+  ENUM_KEY1 = 'ENUM_KEY1',
+  ENUM_KEY2 = 'ENUM_KEY2',
+}
+
+export interface {{ interfaceName }}Props {
+  user?: Record<string, any>
+}
+
+export interface DataType {
+  label: string
+  value: string
+}

package/plop-templates/multiple-pick/data.ts.hbs

@@ -0,0 +1,20 @@
+import type { DataType } from './typing'
+
+const data: Array<DataType> = [
+  {
+    label: '多选项1',
+    value: 'multiple-1',
+  },
+  {
+    label: '多选项2',
+    value: 'multiple-2',
+  },
+  {
+    label: '多选项3',
+    value: 'multiple-3',
+  },
+]
+
+export {
+  data,
+}

package/plop-templates/multiple-pick/hook.ts.hbs

@@ -0,0 +1,11 @@
+import { ref } from 'vue'
+import { data } from './data'
+import type { {{ componentName }}Props } from './typing'
+
+export const use{{ componentName }} = (props: {{ componentName }}Props) => {
+  const selectedValues = ref(props.modelValue ?? data.slice(0, 2).map((item) => item.value))
+
+  return {
+    selectedValues,
+  }
+}

package/plop-templates/multiple-pick/index.normal.vue.hbs

@@ -0,0 +1,37 @@
+<template>
+  <div class="{{ class }}">
+    <div v-for="item in selectedValues" :key="item">{{ item }}</div>
+  </div>
+</template>
+
+<script lang="ts">
+import { defineComponent, PropType } from 'vue'
+import { {{ componentName }}Props } from './typing'
+import { use{{ componentName }} } from './hook'
+
+export default defineComponent({
+  name: '{{ componentName }}',
+  props: {
+    user: {
+      type: Object as PropType<{{ componentName }}Props['user']>,
+      required: false,
+    },
+    modelValue: {
+      type: Array as PropType<{{ componentName }}Props['modelValue']>,
+      required: false,
+      default: () => [],
+    },
+  },
+  setup(props) {
+    const { selectedValues } = use{{ componentName }}(props as {{ componentName }}Props)
+
+    return {
+      selectedValues,
+    }
+  },
+})
+</script>
+
+<style lang="scss" scoped>
+@import './index.scss';
+</style>

package/plop-templates/multiple-pick/index.scss.hbs

@@ -0,0 +1,5 @@
+.{{class}} {
+  position: absolute;
+  top: 0;
+  left: 0;
+}

package/plop-templates/multiple-pick/index.setup.vue.hbs

@@ -0,0 +1,22 @@
+<template>
+  <div class="{{ class }}">
+    <div v-for="item in selectedValues" :key="item">{{ item }}</div>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { {{ componentName }}Props } from './typing'
+import { use{{ componentName }} } from './hook'
+
+defineOptions({
+  name: '{{ componentName }}',
+})
+
+const props = defineProps<{{ componentName }}Props>()
+
+const { selectedValues } = use{{ componentName }}(props)
+</script>
+
+<style lang="scss" scoped>
+@import './index.scss';
+</style>

package/plop-templates/multiple-pick/index.ts.hbs

@@ -0,0 +1,4 @@
+import {{ componentName }} from './src/index.vue'
+
+export default {{ componentName }}
+export * from './src/typing'