huangguo_h5/.cursor/skills/ui-requirement-planner/references/planning-template.md

规划模板

当用户希望获得完整、可执行的前端实施方案时，使用本参考模板。

默认输出模板

需求摘要

• 目标：
• 核心用户：
• 关键操作：
• 约束条件：
• 假设项：

页面与组件架构

• 路由/页面容器职责：
• 组件树：
• 展示型组件：
• 业务组件：
• 可复用候选模块：

状态与数据流

• 页面本地状态：
• 派生状态：
• 交互事件：
• 异步流程：
• 是否需要 Pinia：
• 使用或不使用理由：

API 与类型规划

• Service 模块划分：
• 请求方法：
• 请求参数：
• 响应类型：
• ViewModel 映射：
• 错误模型：

边界与失败状态

• Loading：
• Empty：
• Error：
• Validation：
• Permission：
• Retry/Fallback：

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

• 是否提供真实图片资源：
• 若未提供，采用的占位图方案：
• 占位图尺寸（按 UI 设计尺寸或容器尺寸）：
• 容器比例与 object-fit 策略：
• 多图片位是否分别定义尺寸与样式：

实施步骤

验收清单

• 组件边界清晰，职责拆分明确
• 展示组件内无直接 API 调用
• 仅在必要时使用 Pinia，且理由明确
• Loading / Empty / Error 等状态已覆盖
• 类型定义完整且显式
• scoped scss 职责边界清楚
• 缺图场景有占位图且尺寸符合 UI 设计

骨架目录建议

src/
  pages/
  components/
  composables/
  services/
    http/
    api/
  types/
  utils/

输入到输出示例

示例 1

输入： “做一个用户列表页，支持搜索、筛选、分页、详情抽屉。”

重点关注：

• 表格容器、工具栏、详情抽屉的职责分离
• 查询条件状态是否抽离为 composable
• 详情抽屉是否需要独立拉取逻辑
• loading、empty、retry 状态设计

示例 2

输入： “把这个原型图转成 Vue 页面实现方案。”

重点关注：

• 视觉区域如何映射到组件树
• 通用 UI 基础组件与一次性业务组件的边界
• 占位 API 与类型化 DTO 假设
• 明确的响应式与溢出行为
• 若原型未提供真实图片，给出按 UI 尺寸的占位图方案

示例 3（Figma 素材落地）

输入： “识别 Figma 图标和背景，下载保存到 src/assets/images/png，按模块建目录并正确引用到页面。”

重点关注：

• 图标、背景图、装饰图的分类与复用判断
• 素材目录是否按模块归档
• 文件名是否语义化、可维护
• 页面模板和 TS 里的引用方式是否正确
• 缺失素材时是否有按 UI 尺寸的占位图兜底

可直接复用的输出片段：

### 素材落地清单
- 模块：`mine/newHome`
- 目标目录：`src/assets/images/png/mine/newHome/`
- 素材映射：
  - `icon_message` -> `mine-home-icon-message.png`
  - `icon_setting` -> `mine-home-icon-setting.png`
  - `bg_header` -> `mine-home-bg-header.png`

### 目录结构
```text
src/assets/images/png/mine/newHome/
  mine-home-icon-message.png
  mine-home-icon-setting.png
  mine-home-bg-header.png
  mine-home-banner-placeholder.png
```

### 页面引用建议
- 模板静态引用：
  - `<img src="@/assets/images/png/mine/newHome/mine-home-icon-message.png" alt="message" />`
- TS 计算型引用：
  - `new URL('@/assets/images/png/mine/newHome/mine-home-bg-header.png', import.meta.url).href`

### 占位图策略
- 当 `bg_header` 未交付时，使用 `mine-home-banner-placeholder.png`
- 占位图尺寸：`343 x 84`（按 UI 标注）；若无标注则取容器尺寸
- `object-fit: cover`，确保替换真实图前后布局不抖动