# 规划模板

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

## 默认输出模板

### 需求摘要
- 目标：
- 核心用户：
- 关键操作：
- 约束条件：
- 假设项：

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

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

### API 与类型规划
- Service 模块划分：
- 请求方法：
- 请求参数：
- 响应类型：
- ViewModel 映射：
- 错误模型：

### 边界与失败状态
- Loading：
- Empty：
- Error：
- Validation：
- Permission：
- Retry/Fallback：

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

### 实施步骤
1.
2.
3.
4.

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

### 骨架目录建议
```text
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 尺寸的占位图兜底

可直接复用的输出片段：

````markdown
### 素材落地清单
- 模块：`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`，确保替换真实图前后布局不抖动
````