@agile-team/wl-skills-kit 2.3.1 → 2.3.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [2.3.2] - 2026-04-28
+
+### 📝 输入规范文档体系 + README/目录结构优化
+
+#### 新增 docs/ 输入规范文档（仅仓库可见，不随包分发）
+- **`docs/input-spec-prototype.md`**: 原型输入规范——面向设计师/产品，含合格原型自检清单、按鈕颜色规范、Tab/视角切换标注要求、精度对比表
+- **`docs/input-spec-detailed-design.md`**: 详设文档输入规范——面向业务分析师，含可直接复制的 Markdown 表格模板、字段英文名+字典 code 对精度的量化影响说明
+- **`docs/input-spec-api.md`**: API 契约确认规范——面向后端开发者，含接口 URL 命名规范、api.md 两步确认工作流、常见问题答疑
+- **`docs/input-spec-page-spec.md`**: page-spec JSON 参考手册——面向前端开发者，含每个字段详细注释、自检清单、手写 spec 场景指南
+
+#### 结构和文档优化
+- `README.md`: 版本读数更新为 v2.3，仓库结构图补充 `docs/` 目录说明，“进一步阅读”章节补充输入规范入口
+
+---
+
 ## [2.3.1] - 2026-04-27
 
 ### 🔧 组件三文件分离规范补全 + 文档精准化

package/README.md

@@ -1,6 +1,6 @@
 # @agile-team/wl-skills-kit
 
-**AI Skill 模板包 v2.1** — 一条命令将 13 条编码规范、6 个 AI Skill、组件文档、领域样例导入 Vue 3 项目。
+**AI Skill 模板包 v2.3** — 一条命令将 13 条编码规范、6 个 AI Skill、组件文档、领域样例导入 Vue 3 项目。
 
 让 AI 编辑器（Copilot / Cursor / Windsurf / Claude Code / Cline / Kiro / Trae / 通用 Agents）**真正理解项目规范**，从原型/详设到完整页面代码全流程自动化。
 
@@ -66,6 +66,13 @@ wl-skills-kit/                            ← 你正看的这个仓库
 │   ├── docs/                             组件 API 文档
 │   └── demo/                             领域样例
 │
+├── docs/                                 ★★ 仅仓库可见，不会安装到业务项目 ★★
+│   ├── mcp建议.md                        MCP 进化路线与三层架构建议
+│   ├── input-spec-prototype.md           原型输入规范（面向设计师/产品）
+│   ├── input-spec-detailed-design.md     详设文档输入规范（面向业务分析师）
+│   ├── input-spec-api.md                 API 契约确认规范（面向后端开发者）
+│   └── input-spec-page-spec.md           page-spec JSON 参考手册（面向前端开发者）
+│
 ├── kit-internal/                         ★★ 仅仓库可见，不会安装到业务项目 ★★
 │   ├── README.md                         维护者首页
 │   ├── architecture.md                   架构总览
@@ -240,6 +247,7 @@ npx @agile-team/wl-skills-kit update
 - 🔧 维护者文档：[kit-internal/README.md](kit-internal/README.md)（仅本仓库）
 - 🤖 多编辑器适配机制：[files/.github/skills/_compat/README.md](files/.github/skills/_compat/README.md)
 - 🛠️ Jenkins 流水线参考：[kit-internal/jenkins-pipeline.md](kit-internal/jenkins-pipeline.md)
+- 📝 输入规范（如何提供高精度输入）：[docs/](docs/)
 
 ---
 

package/files/.github/skills/core/page-codegen/templates/_index.md

@@ -15,7 +15,7 @@
 | DETAIL_TABS     | `templates/universal/TPL-DETAIL-TABS.md`    | 详情 Tab 页（上方表单 + 下方 Tab 子表） |
 | CHANGE_HISTORY  | `templates/universal/TPL-CHANGE-HISTORY.md` | 变更历史比对页（时间线 + 字段差异）     |
 | RECORD_FORM     | `templates/universal/TPL-RECORD-FORM.md`    | 录入型实绩页（无分页，查询 + 内联表单） |
-| TEMPLATE_DRIVEN | `templates/universal/TPL-DRIVEN.md`         | 配置驱动识别参考（非代码生成模板）      |
+| TEMPLATE_DRIVEN | `templates/universal/TPL-DRIVEN.md`         | 配置驱动页面（项目已有 Template 组件，data.ts 只需 config 对象，index.vue 3~5 行） |
 
 ---
 

package/files/.github/skills/core/page-codegen/templates/universal/TPL-DRIVEN.md

@@ -1,27 +1,212 @@
-# TEMPLATE_DRIVEN：配置驱动模板页（识别参考）
+# TPL-DRIVEN：配置驱动模板页（TEMPLATE_DRIVEN 模式代码生成模板）
 
-> ⚠️ **本文件为识别参考，不是代码生成模板。**
-> 配置驱动页面已由现有业务模板组件封装，AI **只需生成 config 配置对象**，不得套用 TPL-A 至 TPL-G 的结构重新手写页面逻辑。
+> **本文件是 page-codegen 的正式代码生成模板。**
+> 适用场景：项目中已有可复用的 Template 组件（如 `FinishingAchievementTemplate`），
+> 当前页面的交互骨架与该组件完全一致时，`data.ts` 只需导出 config 对象，`index.vue` 极简到 3~5 行。
 
 ---
 
-## 什么是配置驱动模板页
+## 核心模式：config-only + 3 行 index.vue
 
-这类页面的 `index.vue` 极为简单，只有 1-3 行：
+这类页面的代码精简到极致：
+
+```
+data.ts    → 只导出一个 xxxConfig 常量（纯 TypeScript 对象，无任何业务逻辑）
+index.vue  → 只有 <XxxTemplate :config="config" />，总计 3~5 行
+index.scss → 空文件或极少样式（模板组件内部已处理样式）
+```
+
+所有业务逻辑（查询、表格列、API 调用、确认框、刷新等）全部在 Template 组件内部处理。
+页面文件只是向模板传递"这个页面的具体配置"。
+
+---
+
+## 通用生成规范（适用于任意 Template 组件）
+
+### 步骤 1：确认 Template 组件的 types.ts
+
+生成 config 对象前，必须先读取该模板的类型定义文件：
+
+```
+src/components/template/{XxxTemplate}/types.ts
+```
+
+`data.ts` 的 config 对象结构必须完全遵循 `types.ts` 的 interface 定义，不得猜测字段。
+
+### 步骤 2：生成 data.ts（纯 config 对象）
+
+```typescript
+// src/views/[域]/[模块]/[子模块]/[kebab-页面名]/data.ts
+import type { XxxTemplateConfig } from "@/components/template/XxxTemplate/types";
+
+export const [camelPageName]Config: XxxTemplateConfig = {
+  // 按 types.ts 的 interface 逐字段填写
+  // 所有 API path 格式："/[服务缩写]/[资源名]/[操作]"
+  api: {
+    list: "/[svc]/[resource]/list",
+    // ... 其余 API 按 types.ts 定义
+  },
+
+  // 其他配置字段按 types.ts 补全
+};
+```
+
+> **严格约束**：
+> - ❌ 禁止在 data.ts 中写任何函数、class、ref、reactive
+> - ❌ 禁止导入 `AbstractPageQueryHook` 或任何 hook 基类
+> - ✅ 只有 import type + export const
+
+### 步骤 3：生成 index.vue（3~5 行）
 
 ```vue
+<!-- src/views/[域]/[模块]/[子模块]/[kebab-页面名]/index.vue -->
 <template>
-  <div class="app-container app-page-container">
-    <XxxTemplate :config="xxxConfig" />
-  </div>
+  <XxxTemplate :config="[camelPageName]Config" />
 </template>
 
 <script setup lang="ts">
-import { xxxConfig } from "./data";
+import XxxTemplate from "@/components/template/XxxTemplate/index.vue";
+import { [camelPageName]Config } from "./data";
 </script>
 ```
 
-所有业务逻辑（查询、表格列、导出、翻译等）全部由模板组件内部处理，`data.ts` 只需导出一个 `config` 对象。
+> ⚠️ 注意：模板组件自身已包含 `app-container app-page-container` 外层，
+> index.vue **不要再套一层 div**，避免双层容器导致布局错位。
+> 若不确定，读模板组件的 index.vue 确认其根元素结构。
+
+### 步骤 4：生成 index.scss
+
+通常为空文件或只有极少页面级样式覆盖：
+
+```scss
+// src/views/[域]/[模块]/[子模块]/[kebab-页面名]/index.scss
+// 如无特殊覆盖样式，保留空文件即可
+// 模板组件内部已处理所有通用样式
+```
+
+### 步骤 5：pages.ts 注册（与其他模式相同）
+
+```typescript
+// router/pages.ts 追加
+["[kebab-页面名]", "[页面中文名]"],
+```
+
+---
+
+## 何时使用 TEMPLATE_DRIVEN（识别规则）
+
+**必须同时满足以下两个条件**：
+
+1. 项目 `src/components/template/` 目录下已存在可复用的 Template 组件
+2. 当前页面与该模板的交互骨架**完全一致**（查询/操作/表格结构均与模板期望的 config 结构匹配）
+
+**不确定时的决策**：
+
+```
+✅ 交互完全一致，template/types.ts 字段全部能对应 → 使用 TEMPLATE_DRIVEN
+⚠️ 交互相似但有额外自定义逻辑 → 使用 LIST（更安全，不要强套模板）
+❌ 项目无 Template 组件 → 不适用，直接用 LIST/DETAIL_TABS 等标准模板
+```
+
+---
+
+## 已知配置驱动模板一览（cx-ui-produce 项目特定）
+
+> ⚠️ 以下是 cx-ui-produce 项目已有的 Template 组件，仅在该项目中适用。
+> 其他项目需根据自己项目的 `src/components/template/` 目录确认。
+
+### 1. ResultQueryTemplate（轧钢实绩查询类）
+
+**适用范围**：`production-mmwr/sjtj/` 下的各工序实绩查询页（查询+表格+导出，无新增/编辑/删除）
+
+**识别特征**：
+- 原型中只有查询区 + 数据表格 + 导出按钮
+- 无 CRUD 操作，纯查询
+- 字段较多，表格列数 10+
+
+**生成规则**：
+
+```typescript
+// data.ts — 只导出一个 config 对象
+import type { ResultQueryConfig } from "@/components/template/ResultQueryTemplate/types";
+import { BusLogicDataType } from "@/types/page";
+
+export const [pageName]Config: ResultQueryConfig = {
+  api: {
+    list: "/[服务缩写]/[资源名]/list",
+    export: "/[服务缩写]/[资源名]/export"  // 有导出时才加
+  },
+  queryItems: [
+    { name: "[field]", label: "[中文名]", placeholder: "请输入" },
+    {
+      name: "[dateField]",
+      type: "range",
+      startName: "[startDate]",
+      endName: "[endDate]",
+      label: "[日期名]",
+      logicType: BusLogicDataType.date,
+      rangeSeparator: "至"
+    }
+  ],
+  columns: [
+    { label: "[列名]", name: "[fieldName]", minWidth: 120 }
+  ]
+};
+```
+
+```vue
+<!-- index.vue -->
+<template>
+  <ResultQueryTemplate :config="[pageName]Config" />
+</template>
+
+<script setup lang="ts">
+import ResultQueryTemplate from "@/components/template/ResultQueryTemplate/index.vue";
+import { [pageName]Config } from "./data";
+</script>
+```
+
+---
+
+### 2. FinishingAchievementTemplate（精整实绩类）
+
+**适用范围**：`production-mmwr/jzsj/` 下的各精整工序实绩管理页（喷砂、倒棱、矫直、剥皮、检验、酸洗、包装）
+
+**识别特征**：
+- 原型标题含"实绩"二字且在精整工序列表中
+- 有固定的查询区 + 实绩录入 + 汇总数据结构
+- 字段结构高度统一（同一套模板 7 个页面共用）
+
+**生成规则**：读 `src/components/template/FinishingAchievementTemplate/types.ts`，按 `FinishingAchievementConfig` interface 生成 config 对象。
+
+---
+
+### 3. ApplicationDeterminationTemplate（申请判定类）
+
+**适用范围**：`production-mmwr/` 下的申请判定类页面（如 mmwr-application-determination-jz）
+
+**识别特征**：原型中有"申请"列表 + "判定"操作的双状态工作流页面
+
+---
+
+### 4. SamplingCommissionTemplate（取样委托类）
+
+**适用范围**：`production-mmwr/jhgl/` 下的取样委托管理页
+
+**识别特征**：原型中有"委托单"列表 + 取样记录结构
+
+---
+
+## AI 操作规范
+
+1. **识别阶段**：page-spec 前置检查时，若页面落入以上任一范围或项目有对应 Template 组件，将交互模式标记为 `TEMPLATE_DRIVEN` 并注明具体模板名
+2. **生成阶段**：只生成 `data.ts`（config 对象）+ `index.vue`（3~5行）+ `index.scss`（空或极少样式）
+3. **禁止行为**：
+   - ❌ 不得手写 `createPage()` + `AbstractPageQueryHook` 结构
+   - ❌ 不得添加独立的 `BaseQuery` / `BaseTable` / `jh-pagination`（模板内部已处理）
+   - ❌ 不得将其他业务场景的页面识别为 TEMPLATE_DRIVEN 并强套 config 格式
+4. **不确定时**：使用 LIST 模板代替，更安全
+
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agile-team/wl-skills-kit",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "description": "AI Skill 模板包 — 一键导入 AI 指令 + 组件文档 + 通用组件 + 领域样例，覆盖 Copilot/Cursor/Windsurf/Kiro 等主流 AI 编辑器",
   "main": "./bin/wl-skills.js",
   "bin": {