---
name: ui-requirement-planner
description: 将 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`。