huangguo_h5/.cursor/skills/ui-requirement-planner/SKILL.md

name, description

name	description
ui-requirement-planner	将 UI 需求转化为可维护且可落地的 Vue 3 + Vite + TypeScript 实施方案。适用于用户提供产品需求、Figma 链接/节点、截图、现有页面代码或自然语言想法，并希望输出组件分层、页面结构、composable 抽离、Pinia 使用决策、API 合约规划、交互流程、样式建议、边界状态、素材落地（图标/背景识别、下载、目录归档、页面引用）与验收标准。优先给出可执行方案，再生成代码。

UI 需求规划器

概述

将模糊或分散的 UI 需求整理为可落地的前端实施方案（Vue 3 + Vite + TypeScript）。默认采用“方案优先”输出：先明确页面结构、组件边界、composable、数据流和 API 职责，再给出 Vue 骨架代码。

默认技术栈与约定：

• Vue 3 + Composition API + <script setup lang="ts">
• Vite
• TypeScript（props、emits、API 数据、view model 均需显式类型）
• scoped scss
• Pinia 仅在跨路由或远距离组件共享状态时引入
• axios + 统一请求层 + 统一错误处理

术语统一：

• “素材”默认指 UI 里的图标、背景图、插图、装饰图等静态资源。
• “模块目录”默认指 src/assets/images/png/<module>/（例如 mine/newHome）。

工作流程

除非用户明确要求更小范围交付，否则按以下顺序执行：

1. 读取输入并识别来源：
   • 自然语言需求
   • PRD / 需求单
   • 截图 / 线框描述
   • 现有页面或组件代码
   • 混合输入
2. 将需求归一为简洁的页面目标与主用户路径。
3. 按层拆分 UI：
   • 页面/容器职责
   • 可复用展示组件
   • 业务组件
   • composables
   • store 使用边界
   • API / services 分层
4. 确定状态模型：
   • 页面内状态优先使用 ref / reactive
   • 展示派生状态使用 computed
   • 仅在共享或跨路由场景引入 Pinia
5. 定义 API 边界：
   • service 方法
   • 请求/响应类型
   • loading、empty、error、retry、permission 状态
6. 若输入包含 Figma/原型：执行素材规划与落地策略。
   • 识别图标、背景图、插图等素材位
   • 标记可复用素材与仅页面内使用素材
   • 生成目录归档与命名方案
   • 规划页面中的资源引用方式
7. 产出结构化实施方案。
8. 需要时再补充 Vue 骨架代码或示例文件。

Figma 素材处理规则（新增）

当用户要求“识别 Figma 图标/背景并落地资源”时，必须按以下规则执行：

1. 识别范围

   • 至少区分：功能图标、背景图（整页/卡片）、装饰图、头像占位图。
   • 对同一视觉资源的多处复用，优先抽为同一文件，避免重复导出。

2. 下载与保存路径

   • 统一保存到：src/assets/images/png/<module>/
   • <module> 与业务页面一致，例如：mine/newHome、home/recommend
   • 若资源存在主题态（light/dark）或状态态（default/active/disabled），在文件名中体现。

3. 命名规范

   • 文件名使用小写英文 + 连字符，禁止空格与中文文件名。
   • 推荐模式：<module>-<semantic>-<state?>.png
   • 示例：mine-home-bg.png、mine-home-setting-default.png、mine-home-setting-active.png

4. 页面引用规范

   • Vue SFC 模板内静态引用优先使用别名：@/assets/images/png/...
   • TS 里拼装或计算型资源地址使用：new URL('@/assets/images/png/...', import.meta.url).href
   • 必须确保引用与目录结构一致，避免“移动文件后路径失效”。

5. 无图场景兜底（强制）

   • 缺少真实素材时必须提供占位图，不可空白。
   • 占位图尺寸按 UI 设计尺寸；无标注时按容器尺寸。
   • 方案中需注明占位图来源、尺寸与替换策略（后续替换真实图不改布局）。

输出格式

除非用户要求更短答复，默认按以下结构输出：

1) 需求摘要

• 用 2-4 条概括目标页面/功能
• 说明核心用户目标
• 说明关键业务约束与待确认项

2) 页面与组件架构

• 页面职责
• 组件树
• 哪些组件保持展示型（dumb/presentational）
• 哪些组件承载业务逻辑

3) 状态与数据流

• 本地状态
• 派生状态
• 事件与交互流
• 是否需要 Pinia 及理由

4) API 与类型规划

• 推荐的 services/api 拆分方式
• 请求方法与用途
• 核心类型定义
• 是否需要从原始 API 数据映射到 UI 模型

5) 边界与失败状态

相关场景下必须覆盖：

• loading
• empty
• error
• validation
• permission
• retry / fallback

6) 实施步骤

给出从基础搭建到联调集成的可执行顺序。

7) 验收清单

列出开发者/评审可直接核对的验收点。

8) Vue 骨架代码（按需）

需要时提供精简骨架：

• 页面容器
• 子组件 props / emits
• composable
• store（仅在有充分理由时）
• API service
• 类型定义

9) 图片与占位图规范（强制）

• 若需求未提供真实图片资源（如 banner、封面、头像、商品图等），必须给出占位图方案，禁止留空或“后续补图”而无实现。
• 占位图尺寸必须与 UI 设计尺寸一致：优先使用设计稿标注的宽高；若无明确标注，则以对应容器的宽高作为占位尺寸。
• 在方案与代码中都要明确占位规则（例如：<img> 的 width/height、容器比例、object-fit 策略）。
• 若同一页面包含多种图片位，需分别定义占位图尺寸与样式，不可用一个尺寸通配全部场景。

10) 素材落地清单（Figma/原型场景必填）

• 素材识别结果（图标、背景、装饰图分类）
• 目标目录：src/assets/images/png/<module>/
• 文件命名映射（设计稿节点名 -> 最终文件名）
• 页面引用点位（组件/页面中的引用位置）
• 未交付素材的占位图策略与尺寸

架构规则

组件分层

• 路由页聚焦编排，不要在单文件里混放大段模板 + 业务逻辑 + API 调用。
• 可复用 UI 放入 components/。
• 可复用业务逻辑放入 composables/。
• HTTP 请求逻辑放入 services/ 或 services/api/。
• 跨文件共享类型放入 types/。
• 纯函数工具放入 utils/（需无状态且非 Vue 特定）。

composable 抽离原则

满足任一条件即可考虑抽离：

• 逻辑可复用
• 页面因异步流程或 watchers 变得难以维护
• 表单、列表查询、分页、筛选、权限流程需要独立测试
• 页面中 API 编排与 UI 状态迁移耦合过重

不要为了“挪几行代码”而抽离；抽离应有明确边界价值。

Pinia 使用决策

默认不使用 store。仅在以下场景推荐 Pinia：

• 跨页面共享状态
• 需要持久化的会话态 UI 状态
• 多个远距离组件共同消费同一特性状态
• 单页 composable 无法合理承载的缓存或状态协同

若本地状态足够，需明确说明“不需要 Pinia”。

API 设计

推荐“统一请求客户端 + 薄 service 模块”：

• services/http/client.ts：axios 实例与拦截器
• services/api/<feature>.ts：按业务域组织请求
• types/api.ts 或 feature 内局部 DTO 类型

方案中始终要提及：

• loading 与取消请求策略（如适用）
• 面向用户的错误文案与内部技术错误的区分
• 是否需要将后端字段映射为 view model

错误处理

必须给出一致的错误处理约定：

• 网络与超时失败
• 业务错误码/业务失败
• 参数校验失败
• 乐观更新失败回滚（如适用）
• 可安全重试动作的 retry 机制

避免零散、无模式地到处写 try/catch。

样式规范

默认使用 scoped scss：

• 保持布局 token 与重复样式模式一致
• 避免样式决策导致无关组件强耦合
• 明确指出适合抽离 design token、CSS 变量、共享 mixin 的位置

素材目录与复用边界

• 页面私有素材放 src/assets/images/png/<module>/，跨页面复用素材可上提到共享目录（如 src/assets/images/png/common/）。
• 同一个素材在多个页面复用时，不得各自复制一份，优先统一引用共享文件。
• 若历史文件命名混乱，方案中应给出“保守兼容 + 渐进收敛”的改造建议。

代码生成规则

生成 Vue 代码时：

• 使用 <script setup lang="ts">
• props 与 emits 必须显式类型
• 模板保持可读，避免巨型“全塞一页”
• 有意义的模板表达式应提升为 computed
• 小型展示组件中禁止直接写 axios 调用
• 无充分理由不得引入 Pinia
• 后端细节缺失时可用占位 API 方法与类型，并明确假设
• 缺少真实图片时，必须提供占位图实现，并按 UI 尺寸设置宽高/比例，确保布局稳定不抖动
• 新增素材引用时，必须匹配真实文件路径与命名，不允许“先写引用、后补文件”造成运行时 404

输入不明确时

除非缺失信息会阻断有效推进，否则不要卡住：

• 明确写出假设
• 区分“已确认需求”与“假设项”
• 仍需给出可维护的默认架构方案

典型触发场景

以下请求应使用本技能：

• “把这个后台页面需求拆成 Vue 实现方案”
• “根据这张草图规划组件结构和接口”
• “把这个 UI 需求整理成前端开发任务和代码骨架”
• “这个页面适不适合上 Pinia，接口怎么分层”
• “把现有页面按 composables + services 重构出方案”
• “识别 Figma 图标和背景，下载到 src/assets/images/png 并按模块建目录”
• “把设计稿素材落地并在页面正确引用”

参考

更详细的输出结构与规划提示词见：references/planning-template.md。