页面需求解析技能
将产品策划/需求文档转为结构化的页面描述 Markdown 文件，供后续代码生成 skill 消费。
触发词
解析需求、页面描述、需求转文档、策划转结构化、页面规格定义
依赖
| 来源 | 内容 | 位置 |
|---|---|---|
| 页面描述格式定义 | 文档结构、字段说明、valueType 参考表、推断规则 | references/page-spec-schema.md |
api-doc-scraper skill |
YApi 接口文档采集（补全接口信息） | skill |
输入
用户提供的策划内容，形式不限：
- 文字描述
- 截图
- 文档链接
- 口头描述
输出
> ⚠️ Spec 格式权威声明：当本 skill 的 page-spec-schema.md 与工作流 skill（如 antd-list-page）中定义的 spec 格式不一致时，以工作流 skill 的格式定义为权威。本 skill 的 page-spec-schema.md 仅提供字段语义、推断规则、标注规范等参考，最终产出物的表格结构、列定义必须对齐工作流 skill 的 spec 模板。
保存为 <项目根>/docs/page-specs/{PageName}.md
docs/page-specs/
├── UserManagement.md # 用户管理页
├── RoleManagement.md # 角色管理页
└── KeywordConfig.md # 关键词配置页
文件名使用 PascalCase，与页面组件名一致。
解析方法
1. 识别页面类型
从策划文档中寻找以下关键词判断页面类型：
| 页面类型 | 关键词线索 |
|---|---|
| 列表页 | "列表"、"查询"、"搜索"、"分页"、"批量"、"导出"、"新增/编辑弹窗" |
| 详情页 | "详情"、"查看"、"信息展示"、"只读" |
| 表单页 | "新建"、"编辑"、"提交"、"表单"、"填写" |
2. 提取表格列
寻找线索：策划中的表格结构、字段列表、列定义。
常见策划格式及提取方式：
格式 A：策划自带表格
直接按列提取，每列对应一个表格列条目。
格式 B：字段列表
- 方案名称：文本，可搜索
- 方案类型：下拉选择（语音/会话），可搜索
- 发布状态：标签显示
- 创建时间：时间格式
逐条转为表格列，字段名根据中文标题推断 camelCase。
格式 C：纯文字描述
从描述中提取实体和属性，如"管理质检方案，包含方案名称、类型、状态等字段"→ 提取为表格列。
提取规则：
- 字段名：中文标题转 camelCase（方案名称→planName，创建时间→createTime）
- 如果有接口文档，优先用接口字段名
- 没有接口文档时，字段名为推断值，必须在备注列标注"字段名推断"
- 接口文档补全后，替换推断字段名并移除标注
- 严格按策划提取列，不自行添加策划未提及的列（如创建时间、创建人等，策划没写就不加）
字段名推断规则：
- 基础规则：中文标题直转 camelCase，不加模块前缀（部门名称→name，不是 deptName）
- select 类型字段存储关联实体 ID 时，字段名加 Id 后缀（负责人→leaderId，角色→roleId）
- 主键统一用 id，除非接口文档明确给出其他名称
- 常见映射：名称→name，编码→code，状态→status，时间→createTime/updateTime，数量→count，描述→description
3. 提取弹窗字段
寻找线索："新增"、"编辑"、"弹窗"、"填写"相关描述。
关键判断：
- 弹窗字段通常是表格列的子集（去掉时间戳、状态等自动生成字段）
- 新增和编辑通常共用同一套字段，区别仅在于编辑时有 id
- 策划中"新增时填写 X、Y、Z"→ X/Y/Z 为弹窗字段
- 严格按策划提取弹窗字段，不自行补充策划未提及的字段
- 必填/选填只记录策划明确标注的，策划未说明的不推断，留空即可
- 弹窗有状态字段时，建议在表格也展示状态列，但需在备注标注"策划未明确，建议添加"
- select 类型弹窗字段若关联其他实体（如负责人→用户列表），备注标注"远程请求，数据来源：xxx"
- 枚举选项只写策划明确给出的，策划未提及的选项不编造，备注标注"枚举可能不完整，待确认"
常见差异：
| 表格列有但弹窗没有 | 原因 |
|---|---|
| 创建时间/更新时间 | 系统自动生成 |
| 创建人/更新人 | 系统自动填充 |
| 发布状态 | 新建时默认值 |
| ID | 自动生成 |
| 弹窗有但表格列没有 | 原因 |
|---|---|
| 备注 | 表格不展示但表单可填 |
| 密码 | 表格脱敏，表单可编辑 |
4. 提取操作
寻找线索：动词 + 交互描述。
关联接口列填写规则：填接口表中该接口的 YApi 编号（ID），作为操作表与接口表的精确交叉引用。Step 1 策划解析阶段接口信息未知时留空；Step 2 接口采集后填入 YApi 接口 ID。禁止在此列填写 service 函数名，函数名在代码生成阶段按项目规范生成。
| 策划关键词 | 操作类型 | 触发位置 |
|---|---|---|
| "新增"/"新建"按钮 | 工具栏 | toolBarRender |
| "编辑"行按钮 | 行操作 | 操作列 |
| "删除"行按钮 | 行操作 | 操作列 |
| "查看"/"详情"行按钮 | 行操作 | 操作列 |
| "批量删除"/"批量导出" | 工具栏 | toolBarRender |
| "导出"按钮 | 搜索栏 | search.optionRender |
| "启用/禁用"切换 | 行操作 | 操作列 |
默认操作（策划未明确提及但列表页通常需要的）：
- 新建 → toolBarRender
- 编辑 → 操作列
- 删除 → 操作列（Popconfirm）
- 启用/禁用切换 → 操作列（有状态字段时默认添加）
标注为"策划未明确，按默认添加"。
5. 提取接口
寻找线索：API 路径、接口文档链接、后端对接说明。
核心原则：策划解析阶段不推断接口路径。接口路径必须来自策划原文或接口文档，禁止凭空编造。
提取规则：
1. 策划中明确给出的接口路径 → 直接记录，标注"策划提供"
2. 策划中给出接口文档链接 → 记录链接，标注"待采集"
3. 策划中未提及任何接口信息 → 接口表只填写操作列和备注列，路径/请求方式/参数/响应均留空，备注标注"待接口采集"
禁止事项：
- ❌ 禁止根据操作类型推断接口路径（如列表→/api/xxx/list）
- ❌ 禁止编造请求参数和响应字段
- ❌ 禁止猜测请求方式
接口表填写示例：
策划提供了接口路径时：
| 列表 | /api/sys/department/list | POST | | | 策划提供 |
策划未提供接口信息时：
| 列表 | | | | | 待接口采集 |
| 保存 | | | | | 待接口采集 |
> 接口路径、请求参数、响应字段等具体信息由 Step 2（接口采集）从 YApi 获取并补充，不在策划解析阶段推断。
6. 处理不确定信息
策划文档经常信息不全，处理原则：
| 情况 | 处理方式 |
|---|---|
| 字段名不明确 | 用中文标题推断 camelCase，标注"字段名推断" |
| valueType 不确定 | 按推断规则给出默认值，标注"待确认" |
| 搜索可见性未说明 | 默认 ❌（不搜索），策划明确要求搜索才标 ✅ |
| 必填/选填未说明 | 不推断，留空，策划明确标注才填写 |
| 弹窗字段未说明 | 不自行补充，只提取策划明确提及的字段 |
| 枚举选项不全 | 只写策划明确给出的选项，标注"枚举可能不完整，待确认" |
| 操作未说明 | 添加默认操作（新建/编辑/删除），标注"按默认添加" |
| 接口未提供 | 路径留空，标注"待接口采集"，禁止推断 |
| 策划未提及的列/字段 | 不添加，严格按策划内容提取 |
标注格式：在备注列写"字段名推断"、"待确认"、"待补充"、"策划未明确"、"按默认添加"。
标注优先级："字段名推断" > "待确认" > "策划未明确" > "按默认添加"。同一字段可叠加标注，如"字段名推断，远程请求"。
工作流
Step 1：解析需求
- 阅读用户提供的策划内容
- 读取 references/page-spec-schema.md 获取文档格式和推断规则
- 按解析方法提取：页面信息 → 表格列 → 弹窗字段 → 操作 → 接口
- 按推断规则填充 valueType、搜索可见性、必填等
- 没有接口文档时，所有推断的字段名必须在备注列标注"字段名推断"
Step 2：输出并确认
- 按
page-spec-schema.md定义的格式生成完整描述 - 保存到
docs/page-specs/{PageName}.md - 必须让用户确认，重点确认：
- 标注"字段名推断"的项是否正确
- 标注"待确认"的项是否正确
- valueType 是否合理
- 搜索可见性是否符合预期
- 操作是否完整
- 接口信息是否准确
Step 3：补全（可选）
- 若用户提供 YApi URL，激活
api-doc-scraper采集接口信息 - 用采集结果补全接口表和字段备注（替换"字段名推断"和"待确认"标注）
- 更新文档，再次确认
示例
输入：策划文档片段
质检方案管理页面
列表展示所有质检方案，支持按方案名称和方案类型搜索。
表格字段：
- 方案名称
- 方案类型（语音质检/会话质检）
- 发布状态（未发布/已发布/已下线）
- 维度个数
- 创建人
- 创建时间
操作：
- 新增方案：点击弹出表单，填写方案名称、方案类型、备注
- 编辑方案：行内编辑按钮
- 删除方案：行内删除按钮，需二次确认
输出：结构化页面描述
# 质检方案管理
## 页面信息
| 属性 | 值 |
|------|-----|
| 模块 | Management |
| 路由 | /management/plan |
| 主键 | id |
| 页面类型 | 列表页 |
## 表格列
| 字段 | 标题 | valueType | 搜索 | width | 备注 |
|------|------|-----------|------|-------|------|
| name | 方案名称 | text | ✅ | 160 | 字段名推断 |
| type | 方案类型 | select | ✅ | 120 | 语音质检/会话质检；字段名推断 |
| publishStatus | 发布状态 | select | ❌ | 100 | 未发布/已发布/已下线；字段名推断 |
| dimensionCount | 维度个数 | digit | ❌ | 100 | 字段名推断 |
| creator | 创建人 | text | ❌ | 120 | 字段名推断 |
| createTime | 创建时间 | dateTime | ❌ | 180 | 字段名推断 |
## 弹窗字段
| 字段 | 标题 | valueType | 必填 | width | 备注 |
|------|------|-----------|------|-------|------|
| name | 方案名称 | text | | md | 字段名推断 |
| type | 方案类型 | select | | sm | 语音质检/会话质检；字段名推断 |
| remark | 备注 | textarea | | lg | 字段名推断 |
## 操作
| 类型 | 操作名 | 触发位置 | 关联接口 | 备注 |
|------|--------|---------|---------|------|
| 工具栏 | 新增 | toolBarRender | | 待接口采集 |
| 行操作 | 编辑 | 操作列 | | 待接口采集 |
| 行操作 | 删除 | 操作列 | | Popconfirm 确认；待接口采集 |
| 行操作 | 启用/禁用 | 操作列 | | 按当前状态动态显示相反操作；建议添加；待接口采集 |
## 接口
| 操作 | 接口路径 | 请求方式 | 请求参数 | 响应字段 | 备注 |
|------|---------|---------|---------|---------|------|
| 列表 | | | | | 待接口采集 |
| 保存 | | | | | 待接口采集 |
| 删除 | | | | | 待接口采集 |
注意事项
- 严格按照
page-spec-schema.md定义的格式输出，不要自创格式 - 不确定的字段标注"待确认"或"待补充"，不要猜测
- 没有接口文档时，所有推断的字段名必须在备注列标注"字段名推断"，这是最重要的标注，后续接口文档补全时会替换
- 严格按策划提取，不自行添加策划未提及的列、字段或枚举选项
- 搜索可见性：策划未明确要求搜索的字段，默认 ❌
- 必填/选填：策划未明确标注的，留空不推断
- 枚举选项：只写策划明确给出的，不编造额外选项，标注"枚举可能不完整，待确认"
- 表格列和弹窗字段可能重叠但搜索可见性不同，需分别描述
- 一个页面一个文件
- 中文标题转 camelCase 时注意常见映射：名称→name，类型→type，状态→status，时间→createTime，数量→count，描述→description
- 不要给字段名加模块前缀（部门名称→name 而非 deptName），除非接口文档明确如此
- select 类型字段若关联其他实体，字段名加 Id 后缀（负责人→leaderId），并在备注标注"远程请求，数据来源：xxx"
- 启用/禁用操作是状态切换（toggle），不是单向操作，行按钮文字根据当前状态动态显示
- 启用/禁用操作是状态切换（toggle），不是单向操作，行按钮文字根据当前态动态显示
