page-codegen

name

page-codegen

description

Use when: generating complete Vue 3 page code (index.vue + data.ts + modal components + api.md + pages.ts registration) from a prototype page inventory and API contract, strictly following the cx-ui-produce project conventions. Read SKILL.md first (rules+constraints), then read the matching TPL-*.md for the template code. Triggers on: generate page, create page, code generation, 生成页面, 页面代码, 代码生成, vue页面, 帮我生成, natural language page generation. NOTE: 口述需求/建个页面/写个页面/按原型生成 belong to prototype-scan first (page-codegen chains from it via 模式 0).

Skill: 页面代码生成（page-codegen）

基于《页面清单》+ 原型信息，生成符合项目规范的完整 Vue 3 页面代码。

---

Pre-flight 规范声明（执行前必须输出）

🚀 已触发技能 page-codegen/SKILL.md          → 页面代码生成：骨架文件 + 模板调度 + 前置检查
✅ 已读取 templates/_index.md                → 模板注册表，匹配 → {TPL路径}
✅ 已读取 templates/{universal|domains/xxx}/TPL-XXX.md → {当前模板说明}
✅ 已读取 standards/index.md                 → 规范门控（任务类型 A：生成新页面）
✅ 已读取 standards/02-code-structure.md     → 三文件分离+接口契约 + 三段式 + script 9段顺序
✅ 已读取 standards/12-base-table.md         → AGGrid必用 + cid命名规范
✅ 已读取 standards/13-platform-components.md → 平台组件对照表 + docs前置读取清单
✅ 已读取 standards/14-layout-containers.md   → 布局容器（必须用 jh-drag-row/jh-drag-col）
✅ 已读取 standards/11-form-validation.md     → 表单校验库 + 契约边界（页面含表单时）
✅ 已读取 .wl-skills/docs/{涉及的jh-*文档}              → 当前页涉及组件的使用规范
✅ 已读取 references/component-materialization.md（使用标准业务组件时）→ 按需落盘与契约防护
✅ 已读取 references/form-validation-library.md（页面含表单时）→ Element/RuleSpec API 选择
✅ 工具链检测：.prettierrc.js ✓  eslint.config.ts ✓  .husky/ ✓  [全部就绪]
✅ 表单校验库：@robot-admin/form-validate {版本/不适用}
✅ cid 已生成：{value}（{首字母缩写说明}）

工具链失败时（红叉 + 暂停）：

❌ 工具链检测失败：未找到 .prettierrc.js / eslint.config.ts / .husky/
   → 请执行：npx @robot-admin/git-standards init
   → 或联系 CHENY（工号 409322）解决
   → ⛔ 代码生成已暂停，修复后重新触发

生成完成摘要（生成结束后输出）：

📦 本次生成完成
────────────────────────────────────────────────
✅ src/views/.../{页面}/index.vue
✅ src/views/.../{页面}/data.ts
✅ src/views/.../{页面}/index.scss
✅ src/views/.../{页面}/api.md
✅ src/views/.../{页面}/page-spec.json  → 约定真值（供 S1~S6 比对）
✅ src/views/{域}/{模块}/dicts.ts       → 模块字典发布真值（页面有字典时）
✅ src/components/{local|global}/{组件}/ → 本页需要且原项目缺失时按需落盘
✅ reports/SYS_MENU_INFO.md  → 已追加菜单条目
────────────────────────────────────────────────
🔍 强制自检（不可跳过）：
   wl-skills validate src/views/{生成的页面目录}
   → 同时执行 K1~K19（AST 语义）+ S1~S6（page-spec/机器契约比对）+ C1~C4（组件契约）
   → 结果：{0 error / N warn} 或列出 error 待修复
────────────────────────────────────────────────
📌 后续步骤：
   1. 在 router/pages.ts 注册路由
   2. 若本页 hiddenMenu=true → 在 src/util/navigate-hidden.ts 的 HIDDEN_ROUTE_MAP 追加一行
   3. 提交：git cz（禁止直接 git commit，pre-commit 会自动检测规范）
────────────────────────────────────────────────

生成后强制自检（不可跳过，不可标记为"可选"）

v2.10.0+ 硬约束：生成页面代码后，AI 必须立即执行规范自检，不可跳过。

1. 调用 MCP 工具 wls_validate_page，path 参数为本次生成的页面目录（精确到具体页面，不传 src/views 全局）
2. 如有 error：
   • 仅修复本次生成的文件中的 error（index.vue / data.ts / index.scss / api.md）
   • 如 error 来自同目录下的旧文件（非本次生成），不要修改，在摘要中标注"已跳过 N 个旧文件 error"
   • 修复后重新自检直到本次生成的文件 0 error
3. 如有 warn → 尝试修复，确实无法修复的在摘要中说明原因
4. 自检结果（error 数 / warn 数 / 跳过的旧文件数）写入上方"生成完成摘要"
5. 自检范围为本次生成的单个页面目录，不对无关页面负责

这条规则确保 AI 不会"写完就跑"——生成和验证形成闭环。 作用域隔离原则：AI 只对自己本次生成的文件负责，不强制修复历史遗留偏差。 git commit 时 pre-commit hook 会再次拦截，但 AI 应在生成阶段就消除本次生成的 error。

---

前置检查

□ 页面中文名：
□ 交互模式：LIST / MASTER_DETAIL / TREE_LIST / DETAIL_TABS / FORM_ROUTE / CHANGE_HISTORY / RECORD_FORM / OPERATION_STATION / TEMPLATE_DRIVEN
□ page-spec JSON：（必须存在，由 prototype-scan 输出）
□ 文件路径：src/views/[域]/[模块]/[子模块]/[kebab-case-目录名]/
□ pages.ts 注册名：["kebab-目录名", "中文名"]
□ 服务缩写：[pm / mmwr / sale / ...]
□ 资源名(CamelCase)：

重要：查询字段、表格列、按钮列表不再手动罗列，直接从 page-spec JSON 中读取。 如果没有 page-spec JSON，必须先执行 prototype-scan Skill 生成。

模式 0 快捷路径：当用户直接口述需求（如"帮我生成一个客户管理页面"）而未提供 page-spec JSON 时，AI 内部自动调用 prototype-scan 模式 0 构建 page-spec JSON，然后继续执行代码生成，无需用户提供任何文件。

---

生成产物（标准页面文件）

src/views/[域]/[模块]/[子模块]/[kebab-case-目录名]/
├── index.vue       ← 页面入口（纯模板 + 解构）
├── data.ts         ← 业务逻辑（AbstractPageQueryHook 类 / 直接导出 ref+函数）
├── index.scss      ← 页面样式
├── api.md          ← 接口约定（按 api-contract Skill 模板生成）
└── page-spec.json  ← ★ 原型约定真值（查询/列/按钮/操作列 顺序+颜色），供 validate S1~S6 确定性比对

页面使用字典时，在模块根目录额外维护 dicts.ts：

src/views/[域]/[模块]/dicts.ts

先在页面 api.md 写完整 dict-contract，再合并到 dicts.ts；读取 .wl-skills/docs/dictionary-contract.md。不得仅在 data.ts 写 logicValue 而缺少字典定义。

page-spec.json 是"精准实现"的真值锚点：把 page-spec（查询字段顺序、列顺序、按钮顺序与颜色、操作列）固化到页面目录，wl-skills validate 据此比对 data.ts 实际实现，偏差即报（详见 .wl-skills/docs/page-spec-schema.md）。不可省略——没有它，"按约定实现"无法被验证，只能靠 AI 自觉。

弹窗组件处理策略：

• kit 标准组件 → 按 references/component-materialization.md 预览并按需落盘到 src/components/local/；.wl-skills 仅为模板源
• 项目通用弹窗（新增/编辑表单，2+ 页面复用）→ 提取到 src/components/local/c_xxxModal/
• 极个性弹窗（仅单页面使用，c_modal 无法满足）→ 放在页面 components/xxxModal.vue

附加输出：

• pages.ts 注册片段
• reports/SYS_MENU_INFO.md — 集中式菜单配置，追加写入（见下方 §SYS_MENU_INFO 生成规则）
• mock/[业务域]/[模块].ts（仅当 .wl-skills-validate.json.mockPolicy 为 required，或 optional 且需求明确需要 mock 时生成；disabled 时禁止生成。详见 .wl-skills/docs/mock-architecture.md）

wl-skills-ui 生成闭环契约

生成代码应直接遵守 @agile-team/wl-skills-ui 的控件几何和列表布局契约，避免让业务页再用 CSS 补救：

• 所有直接生成的 el-input、el-input-number、jh-select、jh-date 等输入控件显式使用 size="small"（或等价的 size 配置），保留标准 placeholder；不得在页面样式中把 .el-input__inner、.el-input__wrapper 的 padding 清零。展示值、只读值与 placeholder 必须复用同一控件结构和间距。
• 数字输入框只声明业务语义（controls、textAlign 等）；不得在页面中隐藏步进按钮、重写箭头的绝对定位或高度。UI 包统一负责右侧上下箭头的几何。
• 复杂表单控件在表单列中统一 width: 100%，避免选择器、日期、数字框宽度漂移。
• 列表分页必须位于表格之后的独立 .list-page__pager 容器，并右对齐；不要把分页器塞进表格或工具栏布局。
• 操作列必须 fixed: "right"、align: "center"，使用 renderOps 图标语义；宽度按同时可见按钮最大数量确定（2 个约 140px，3 个约 200px），查看/编辑/删除不得生成裸文字按钮。
• 状态/字典列必须使用 logicType: BusLogicDataType.dict 或 runtime Tag 渲染，不生成无语义的纯文本状态列。

生成完成后的页面自检除既有 K1K19/S1S6/C1~C4 外，还必须确认：分页器容器和位置、操作列固定/对齐/宽度、状态 Tag、输入控件 size/placeholder/间距，以及数字框未被业务 CSS 改写。

---

约束（严格遵守）

必须

1. data.ts 使用 class extends AbstractPageQueryHook，通过 queryDef() / toolbarDef() / columnsDef() 配置。仅适用于 LIST / MASTER_DETAIL / TREE_LIST 三种列表型页面。其余模板不用此基类：DETAIL_TABS（直接导出 reactive+ref）、FORM_ROUTE（useXxx composable）、CHANGE_HISTORY（composable+mock）、RECORD_FORM（直接 ref+函数）、OPERATION_STATION（多个 createXxxPage）、TEMPLATE_DRIVEN（仅 config 对象）
2. index.vue 只有模板 + createPage() 解构 + onMounted，不写业务逻辑。例外：DETAIL_TABS / FORM_ROUTE / CHANGE_HISTORY 的 index.vue 可包含表单状态管理；OPERATION_STATION 包含 computed/watch/多列表协调逻辑
3. 最外层 class：app-container app-page-container
4. 样式用 @import "./index.scss"
5. API 用 getAction / postAction from @jhlc/common-core/src/api/action
6. 字典字段用 logicType: BusLogicDataType.dict, logicValue: "dictCode"
7. 同时生成 api.md（基于 api-contract Skill 模板）；有字典时写 dict-contract 并更新模块 dicts.ts
8. 提供 pages.ts 注册片段
9. Mock 遵循项目策略：读取 .wl-skills-validate.json.mockPolicy。disabled 不生成、不安装、不校验 mock；optional（默认）仅在用户明确需要时生成；required 必须生成。启用时放在 mock/[业务域]/，URL/字段/方法/载荷与 api.md 及生效 Delivery Profile 一致，并复用 ../_utils
10. 查询字段顺序：queryDef() 中字段顺序必须与 page-spec query 数组顺序严格一致（即原型从左到右、从上到下）
11. 表格列顺序：columnsDef() 中列顺序必须与 page-spec columns 数组顺序严格一致（selection + index 在最前，其余按原型表头从左到右）
12. 按钮顺序与颜色：toolbarDef() 中按钮顺序、name（颜色）和 plain（填充/线框）必须与 page-spec toolbar 数组严格一致（primary=蓝底, danger=红色, warning=橙色, default=灰色; plain: true=线框）。"新增/新建/添加/创建"类主按钮永远排第一，并强制 name: "primary" 且不得设置 plain: true；生成后 S3 必须同时校验颜色和 plain 形态。
13. 长文本列：普通文本列统一声明 showOverflowTooltip: true，列宽不足时显示省略号，悬停展示完整内容；selection/index/操作列、自定义 Tag 渲染列以及 wrapText/autoHeight 列不得机械添加。

禁止事项（严格遵守）

1. ❌ 禁止手写弹窗：不可在页面 components/ 下用 el-dialog + el-form + el-row/col 手写弹窗。必须使用按需落盘到 src/components/local/c_formModal/ 的 c_formModal，通过 modalConfig 配置驱动；禁止运行时引用 .wl-skills。例外：纯只读详情弹窗（jh-dialog + BaseForm :disabled="true"）可不用 c_formModal，如工艺参数查看（参考 mmwr-process-parameters）
2. ❌ 禁止在弹窗中使用原生 Element Plus 组件：不可使用 el-select、el-input、el-date-picker 等原生组件，必须使用 jh-select、jh-date、jh-user-picker 等平台组件（通过 BaseFormItemDesc 的 component 属性配置）
3. ❌ 禁止在 BaseToolbar 内使用 slot：BaseToolbar 组件不支持任何 slot（源码中无 <slot> 标签），放入的内容会被丢弃不渲染。Tab/视角切换等额外 UI 必须放在 BaseToolbar 外部
4. ❌ 禁止用 el-radio-group 做 Tab/视角切换：所有 Tab 式切换（视角切换、数据过滤 Tab、功能 Tab）必须使用 el-tabs（参考 mmwr-steel-stripping-operations）。不可用 el-radio-group + 手动 handleViewChange / handleTabChange
5. ❌ 禁止 Mock 端点只返回成功不修改数据：mock 文件中每个端点的 response 必须实际修改 dataPool（splice/assign/修改字段），否则 this.select() 刷新后数据不变。详见 §Mock 端点最佳实践
6. ❌ 禁止遗留未使用的 import：data.ts 中不要导入未使用的模块（如仅用 postAction 时不导入 getAction）
7. ❌ 禁止操作列自编按钮：操作列的 operations 数组必须与原型操作列按钮严格一致，不可凭空添加原型中不存在的按钮（如原型只有"编辑"+"删除"，不可自行加"查看"）
8. ❌ 状态类列必须 fixed: "right" + 色块渲染：启用状态、停用时间、转化状态、客户状态、审批状态、核实状态等靠近操作列的状态类列必须设置 fixed: "right"，与操作列一起固定在表格右侧。且状态列必须用 defaultSlot + h(ElTag) 渲染彩色标签，不可纯文本显示（详见 §状态列色块渲染模式）
9. ❌ 禁止操作按钮标签自编：操作列按钮 label 必须与原型严格一致（如原型写"修改"不可改成"编辑"，写"作废"不可改成"删除"），且 onClick 逻辑必须匹配语义（"作废"调 cancel API，不是 remove）
10. ❌ 禁止平台组件遗漏 ：在 el-form-item 内使用 、、 时， 隐藏组件自身标签（否则会渲染"下拉选择框："、"日期："等多余文字）

场景化实现规则（按需读取）

命中场景	必读 reference
pattern 已实现且规格能落进 scenario JSON（确定性渲染前置层）	references/scenario-templates.md
CRUD 弹窗、蓝色链接列或 FORM_ROUTE 隐藏路由	references/modal-and-navigation.md
按钮交互、条件操作列、状态标签或视角/Tab	references/table-interactions.md
Excel 导入导出或 Mock 写操作	references/import-export-and-mock.md
FORM_TAB / FORM_ROUTE / 独立路由表单页	references/form-ui.md
新增/编辑表单、可编辑明细或提交前批量校验	references/form-validation-library.md
写入 pages.ts 或 SYS_MENU_INFO.md 前	references/registration-and-menu.md

只读取本次页面命中的 reference；模板代码仍按下方模板索引读取一个匹配文件。

禁止

以下为精简速查清单，详细说明见上方 §禁止事项（严格遵守）。

• ❌ index.vue 中写业务逻辑（逻辑全在 data.ts）
• ❌ 使用 Vuex（用 Pinia）
• ❌ ::v-deep / /deep/（用 :deep()）
• ❌ 直接用 axios（用 getAction/postAction）
• ❌ 手写查询表单/工具栏/分页（用 BaseQuery/BaseToolbar/jh-pagination）
• ❌ 使用 useTableDelete（用 this.remove(row.id)）
• ❌ 用 { ...instance } 展开 create() 返回值
• ❌ Mock 端点不修改 dataPool、字段名不对齐 columnsDef
• ❌ data.ts 导入未使用的模块
• ❌ 用 el-radio-group 做 Tab/视角切换（统一用 el-tabs）

---

表单页 UI 路由

FORM_TAB、FORM_ROUTE 或独立路由表单页必须读取 references/form-ui.md；列表页不加载。

api.md 生成时序

api.md 在页面代码之前生成（Step 2: api-contract → Step 3: page-codegen）。 page-codegen 读取已生成的 api.md 中的 URL 和字段定义，确保 API_CONFIG、mock、data.ts 与接口约定一致。 未来使用真实 API 设计文档时，api.md 由后端提供或 api-contract Skill 从设计文档提取，page-codegen 直接消费。 页面含字典时，在生成 data.ts 前先完成 api.md dict-contract → 模块 dicts.ts 合并，生成结束后由 validate D1 复核。

---

页面注册与菜单报告

生成 pages.ts 注册片段和追加 reports/SYS_MENU_INFO.md 前，必须读取 references/registration-and-menu.md，确保 component 路径、菜单层级和追加策略一致。

代码模板索引

各模板完整代码见对应独立文件，按需读取。主文件（SKILL.md）包含前置检查、约束、按钮规则、Mock规范等所有共用规则。

交互模式	文件	适用场景	典型参考页面
LIST	templates/universal/TPL-LIST.md	标准查询+工具栏+表格+分页	mmwr-customer-archive
MASTER_DETAIL	templates/universal/TPL-MASTER-DETAIL.md	jh-drag-row 主从表，双击联动	ompt-ht-plan-order
TREE_LIST	templates/universal/TPL-TREE-LIST.md	左侧 C_Tree + 右侧列表	—
DETAIL_TABS	templates/universal/TPL-DETAIL-TABS.md	jh-drag-row 上Tab表单+下子表	add-demo / domestic-trade-order
FORM_ROUTE	templates/universal/TPL-FORM-ROUTE.md	复杂表单独立路由（非弹窗）	mmwr-customer-apply-add-form
CHANGE_HISTORY	templates/universal/TPL-CHANGE-HISTORY.md	左历史时间线+右变更详情	mmwr-customer-apply-change-history
RECORD_FORM	templates/universal/TPL-RECORD-FORM.md	BaseQuery选主记录+Form+Table无分页	mmsm-convert-progress
OPERATION_STATION	templates/domains/produce/TPL-OPERATION-STATION.md	工序站点操作（待处理↔已处理+操作表单）	mmwr-rolling-management

配置驱动模板页（ResultQueryTemplate / FinishingAchievementTemplate 等）：见 templates/universal/TPL-DRIVEN.md，仅需生成 config 对象，不套用以上模板。 领域模板查询：完整路径以 templates/_index.md 注册表为准，新增领域模板见 templates/domains/_CONTRIBUTING.md。