240 lines
9.6 KiB
Markdown
240 lines
9.6 KiB
Markdown
---
|
||
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`。
|