02 — 原型设计规范
📦 来源：
wl-skills-designv0.11.1 ·standards/02-prototype.md· 可判定条目由verify（[M] 机械项）自动执行。
wl-skills-design · requirements-prototype 本文档是原型设计的唯一权威规范来源，工具无关（Axure / Figma / 即时设计 / MasterGo 均适用）。 所有 AI 工具读取此文件作为执行依据，不得凭记忆或推断覆盖本规范。
设计原则：原型是需求设计说明书（06-spec-doc）的可视化补充，不替代 IPO 表。 原型的核心目的是固定页面布局、交互模式和字段位置，为下游
prototype-scan→page-codegen提供精确输入。
§一 原型在全链路中的定位
需求设计说明书（IPO 表）
↓ 确定功能清单 + 字段 + 处理逻辑
原型设计（本规范）
↓ 固定页面布局 + 交互模式 + 组件选型
prototype-scan（wl-skills-kit）
↓ 输出 page-spec JSON
page-codegen → 代码生成1.1 与 spec 的关系
| 维度 | spec（06-spec-doc） | 原型（本规范） |
|---|---|---|
| 关注点 | 处理逻辑、数据流、校验规则 | 页面布局、交互方式、视觉层级 |
| 输出格式 | Markdown IPO 表 | 页面标注图 + 交互说明 |
| 消费方 | 数据库设计 / 接口设计 / 评审 | prototype-scan / 前端开发 |
| 字段来源 | 原型中的字段必须 ⊆ spec IPO 字段 | — |
1.2 原型不做什么
- ❌ 不定义处理逻辑（那是 spec IPO 的职责）
- ❌ 不定义接口契约（那是 api-design 的职责）
- ❌ 不做视觉设计（颜色/字体/间距由 UI 规范或设计系统决定）
- ❌ 不写死数据内容（用占位符，不用线上业务数据）
§二 页面交互模式分类
所有页面必须归入以下模式之一，AI 据此选择组件组合和布局结构。
| 模式代码 | 模式名称 | 通用场景 | 布局结构 |
|---|---|---|---|
LIST | 标准列表页 | 申请列表、任务台账、审核记录 | 查询区 + 工具栏 + 表格 + 分页 |
FORM_MODAL | 弹窗表单 | 新增/编辑申请、审核弹窗 | 弹窗 + 表单分区 + 按钮组 |
FORM_ROUTE | 路由表单 | 复杂新增（多步骤）、详情页 | 独立页面 + 表单分区 + 步骤条（可选） |
MASTER_DETAIL | 主从表 | 申请主档+明细、任务+子任务 | 上下或左右分栏 |
TREE_LIST | 树形+列表 | 分类树+记录、目录+条目 | 左右分割 |
TAB_FORM | 多 Tab 表单 | 基础资料维护（多维度属性） | Tab 切换 + 各 Tab 内表单/表格 |
DASHBOARD | 仪表盘 | 任务看板、处理时效 | 卡片 + 图表 + 统计指标 |
COMPOSITE | 组合页面 | 任务编排（查询+分组+明细） | 多模式组合，需逐区标注 |
2.1 模式选择决策树
页面有左侧树形导航？
├── 是 → TREE_LIST
└── 否 → 页面有上下两个关联表格？
├── 是 → MASTER_DETAIL
└── 否 → 页面主体是表格+CRUD？
├── 是 → LIST（新增/编辑用弹窗=FORM_MODAL，用独立页=FORM_ROUTE）
└── 否 → 页面主体是图表/指标？
├── 是 → DASHBOARD
└── 否 → 页面有多个 Tab 切换？
├── 是 → TAB_FORM
└── 否 → COMPOSITE（需拆解标注）§三 原型标注规范（每页必须输出的内容）
每个页面的原型标注必须包含以下 7 项，缺一不可。
3.1 页面元信息（必填）
markdown
## {页面中文名}
- **交互模式**：LIST / FORM_MODAL / MASTER_DETAIL / ...
- **目录名**：kebab-case（如 request-review）
- **服务缩写**：模块缩写（如 produce / sale / quality）
- **所属流程**：关联的系统流程编号（如 PLAN-A-01）
- **关联 IPO**：spec 中对应的功能编码（如 PLAN007）3.2 查询区标注
| 必须标注项 | 说明 | 示例 |
|---|---|---|
| 字段名（camelCase） | 与 data.ts 直接对应 | orderNo |
| 中文标签 | 显示文本 | 申请编号 |
| 组件类型 | input / dict / date / dateRange / userPicker / deptPicker | dict |
| 字典编码 | 仅 dict 类型必填 | order_status |
| 是否必填 | 查询条件是否必填 | 否 |
3.3 表格列标注
| 必须标注项 | 说明 | 示例 |
|---|---|---|
| 字段名（camelCase） | 与接口返回字段对应 | planStatus |
| 中文表头 | 列标题 | 申请状态 |
| 列宽（px） | 建议宽度 | 120 |
| 字典编码 | 需要翻译的字段 | mmwr_plan_status |
| 是否可点击 | 蓝色/下划线=可点击跳转 | 是（跳转详情） |
| 排序 | 是否支持排序 | 否 |
3.4 工具栏按钮标注
| 必须标注项 | 说明 | 示例 |
|---|---|---|
| 按钮文案 | 与原型完全一致 | 新增 |
| 按钮类型 | primary / success / warning / danger / default | primary |
| 触发动作 | openModal / batchDelete / export / import / ... | openModal |
| 权限标识 | 按钮级权限编码（可选） | plan:add |
3.5 操作列按钮标注
| 必须标注项 | 说明 | 示例 |
|---|---|---|
| 按钮文案 | 与原型完全一致（不可自行替换） | 编辑 / 删除 / 提交 |
| 触发动作 | edit / delete / submit / detail / ... | edit |
| 条件显示 | 按状态/权限控制显隐 | status === 0 时显示 |
3.6 表单字段标注（弹窗/路由表单）
| 必须标注项 | 说明 | 示例 |
|---|---|---|
| 字段名（camelCase） | 与接口提交字段对应 | productType |
| 中文标签 | 表单 label | 申请类型 |
| 组件类型 | input / select / date / number / textarea / ... | select |
| 是否必填 | 表单校验 | 是 |
| 字典编码 | 下拉选项来源 | request_type |
| 默认值 | 有则标注 | — |
| 联动规则 | 字段间联动（可选） | 选择申请类型后显示补充说明 |
3.7 特殊交互标注
针对非标准交互，必须额外标注：
| 交互类型 | 标注内容 |
|---|---|
| 状态机按钮 | 各状态下按钮的显隐规则 |
| 批量操作 | 勾选规则（跨页？全选？） |
| 拖拽排序 | 哪些行/列支持拖拽 |
| 行内编辑 | 哪些列支持直接编辑 |
| 子表格展开 | 展开行的内容结构 |
| 审批流 | 审批节点与按钮映射 |
§四 原型输出深度标准
不同阶段对原型的精度要求不同。本规范定义三个深度等级。
4.1 深度等级定义
| 等级 | 名称 | 适用阶段 | 精度要求 | 输出物 |
|---|---|---|---|---|
| D1 | 布局骨架 | 需求评审前 | 确定模式+区域划分，字段可用占位符 | 灰度线框图 |
| D2 | 字段完整 | 需求评审后 | 所有字段名+类型+字典确定，交互规则明确 | 带标注的原型 |
| D3 | 开发就绪 | 进入开发前 | 满足 §三 全部 7 项标注，可直接 prototype-scan | 完整标注原型 |
4.2 各等级必须达到的标注项
| 标注项 | D1 | D2 | D3 |
|---|---|---|---|
| 页面元信息 | ✅ | ✅ | ✅ |
| 交互模式确定 | ✅ | ✅ | ✅ |
| 查询区字段（中文名） | ○ 占位 | ✅ | ✅ |
| 查询区字段（camelCase + 组件类型） | — | ✅ | ✅ |
| 表格列（中文名） | ○ 占位 | ✅ | ✅ |
| 表格列（camelCase + 宽度 + 字典） | — | ✅ | ✅ |
| 工具栏按钮 | ○ 占位 | ✅ | ✅ |
| 操作列按钮 | — | ✅ | ✅ |
| 表单字段完整标注 | — | ○ 主要字段 | ✅ |
| 特殊交互标注 | — | — | ✅ |
| 状态机/条件显隐 | — | — | ✅ |
交付标准：进入开发的原型必须达到 D3。D1/D2 仅用于评审沟通。
§五 原型与 spec 的字段对齐规则
5.1 字段来源约束
原型中出现的所有业务字段 ⊆ spec IPO 表中定义的字段- 原型不得凭空新增 spec 中未定义的业务字段
- 如需新增字段，先补 spec IPO 表，再更新原型
- 系统字段（创建人/创建时间/更新人/更新时间）无需在 spec 中定义，原型可直接使用
5.2 字段命名一致性
| 层级 | 命名格式 | 示例 |
|---|---|---|
| 原型标注 | camelCase | productType |
| spec IPO | 中文名 | 申请类型 |
| 数据库 | snake_case | request_type |
| 接口 | camelCase | productType |
原型标注的 camelCase 字段名 = 接口字段名 = 术语词典（08-glossary）中的英文名。 如已建立术语词典，原型字段命名必须从词典中取。
5.3 联动校验（与集成评审 D4 对接）
集成评审时，D4 维度会校验：
- 原型中的字段是否都能在 spec IPO 中找到对应
- 原型中的字典编码是否与数据库枚举定义一致
- 原型中的按钮是否都有对应的接口
§六 页面编码与命名规范
6.1 页面编码 = spec 功能编码（不另建体系）
原型不定义新的编码体系。一个原型页面 = spec 中的一个功能（4.x.4.z）， 直接复用 spec 06-spec-doc §10.4 的功能编码
[子模块代码][NNN]。
spec 功能编码 → 原型页面标注 → prototype-scan → 代码目录
REQ001 REQ001 申请列表 page-spec request-list/| 来源 | 编码 | 示例 |
|---|---|---|
| spec 功能编码（权威） | [子模块代码][NNN] | PLAN007 |
| 原型页面元信息「关联 IPO」 | 引用 spec 功能编码 | PLAN007 |
- 一个功能编码对应一个主页面（含其新增页/修改页等子页面）
- 原型页面不得出现 spec 中不存在的功能编码（详见 §九 PT-X X05）
- COMPOSITE 类页面若由多个功能编码组成，逐个列出关联编码
6.2 目录命名规范
views/{服务缩写}/{业务域}/{子模块kebab}/{页面kebab}/示例：views/request/request-list/
6.3 文件命名规范（生成后的代码文件）
| 文件 | 命名 | 说明 |
|---|---|---|
| 页面入口 | index.vue | 主视图 |
| 逻辑层 | useXxx.ts | 组合式函数 |
| 数据层 | data.ts | 字段定义 + 字典 + 列配置 |
| Mock | mock.ts | 开发阶段 Mock 数据 |
§七 项目扩展画像
包内不预置客户或行业约定。项目若有专用字典、计量单位、隐私展示或复杂交互，应在设计画像中显式声明；未声明时先询问，不得从样例推断。
7.1 画像字段
| 配置 | 说明 | 示例 |
|---|---|---|
dictionarySource | 字典权威来源与版本 | docs/glossary.md |
unitPolicy | 单位、精度与换算规则 | 数量为整数，金额保留 2 位 |
privacyDisplay | 脱敏、掩码与权限规则 | 联系方式按角色掩码 |
interactionPatterns | 项目特有交互及适用页面 | 批量审批仅用于待审核列表 |
accessibility | 键盘、对比度和读屏要求 | WCAG 2.2 AA |
7.2 扩展规则
- 字典编码必须来自画像或词典，不得根据中文名猜测。
- 项目特有交互必须记录触发条件、权限、失败反馈和可逆性。
- 展示敏感字段时同时标注可见角色、掩码方式和复制限制。
- 画像缺失的扩展项标“待确认”，不得写成默认实现。
§八 原型交付物清单
8.1 单页面交付物
每个页面完成后，必须产出：
| 序号 | 交付物 | 格式 | 说明 |
|---|---|---|---|
| 1 | 页面标注图 | PNG/PDF/Axure | 含所有区域标注 |
| 2 | 字段清单 | Markdown 表格 | 按 §三 格式，可直接被 prototype-scan 消费 |
| 3 | 交互说明 | Markdown | 状态机/联动/条件显隐等非标交互 |
8.2 模块级交付物
一个模块所有页面完成后，汇总产出：
| 序号 | 交付物 | 格式 | 说明 |
|---|---|---|---|
| 1 | 页面清单总表 | Markdown 表格 | 页面名/模式/目录名/关联流程 |
| 2 | 页面导航关系图 | 文字描述或简图 | 页面间跳转关系 |
| 3 | 字典汇总表 | Markdown 表格 | 本模块用到的所有字典编码 |
§九 验证清单（PT-A/B/C/X 四组，共 23 项）
验证时按组执行，每组内按编号顺序逐项检查。
PT-A 组：页面完整性（5 项）
| 编号 | 检查项 | 严重度 |
|---|---|---|
| A01 | 每个页面都标注了交互模式 | P0 |
| A02 | 每个页面都有页面元信息（目录名/服务缩写/关联流程） | P0 |
| A03 | 查询区字段数量与标注一致（不多不少） | P1 |
| A04 | 表格列数量与标注一致 | P1 |
| A05 | 工具栏按钮和操作列按钮都已标注 | P1 |
PT-B 组：字段规范性（7 项）
| 编号 | 检查项 | 严重度 |
|---|---|---|
| B01 | 所有字段名使用 camelCase 格式 | P1 |
| B02 | 所有 dict 类型字段都标注了 dictCode | P0 |
| B03 | 日期字段明确了类型（date / dateRange / month） | P1 |
| B04 | 表单必填字段已标注 | P1 |
| B05 | 字段名与术语词典（如有）一致 | P1 |
| B06 | 表格列宽度合理（总宽不超容器宽度） | P2 |
| B07 | 可点击列已标注跳转目标 | P1 |
PT-C 组：交互完整性（6 项）
| 编号 | 检查项 | 严重度 |
|---|---|---|
| C01 | 状态机页面的按钮显隐规则已标注 | P0 |
| C02 | 主从表的主表选中→从表联动已说明 | P1 |
| C03 | 批量操作的勾选规则已说明 | P1 |
| C04 | 弹窗/路由表单的字段分区已标注 | P2 |
| C05 | 联动字段的触发规则已说明 | P1 |
| C06 | 审批流页面的节点→按钮映射已标注 | P1 |
PT-X 组：跨文档一致性（5 项）
| 编号 | 检查项 | 严重度 |
|---|---|---|
| X01 | 原型字段 ⊆ spec IPO 字段（无 spec 外字段） | P0 |
| X02 | 原型字典编码与数据库枚举定义一致 | P1 |
| X03 | 原型按钮都有对应的 spec 处理逻辑 | P1 |
| X04 | 原型字段命名与术语词典一致（词典存在时） | P1 |
| X05 | 原型页面的「关联 IPO」编码在 spec 4.x.4 功能设计中存在（无孤立页面） | P0 |
§十 闭环修复协议
10.1 验证→修复流程
执行验证清单（23 项）
↓
发现问题 → 按严重度分级（P0/P1/P2）
↓
P0：立即修复，修复后复验
P1：本轮修复，修复后复验
P2：记录待优化，不阻断
↓
全部 P0/P1 通过 → 原型达到 D3，可进入开发10.2 修复优先级
| 严重度 | 含义 | 处理方式 |
|---|---|---|
| P0 | 阻断：缺失关键标注，prototype-scan 无法正确解析 | 必须修复 |
| P1 | 重要：影响代码生成质量，但不阻断解析 | 应当修复 |
| P2 | 建议：优化项，不影响功能 | 可延后 |
§十一 与下游工具的对接约定
11.1 prototype-scan 消费格式
原型标注的最终输出格式应可被 prototype-scan Skill 直接消费，转换为 page-spec JSON：
json
{
"pageName": "申请列表",
"kebabName": "request-list",
"pattern": "LIST",
"path": "views/request/request-list/",
"query": [...],
"toolbar": [...],
"columns": [...],
"operations": [...]
}11.2 与集成评审的关系
原型设计 Skill 已发布。集成评审（07-design-review）在提供原型产物时增加以下扩展检查：
- 原型字段 ⊆ spec IPO 字段
- 原型字典 = DB 枚举
- 原型按钮 → 接口覆盖
代码设计视角：原型标注是
page-codegen的直接输入。标注越精确，生成代码的还原度越高。 D3 级原型可作为代码生成输入；实际还原质量必须由固定语料、目标框架和可复现评测确认，不作未经验证的百分比承诺。