初始化

2026-09-15 15:25:05 +07:00
commit 77c16ab4a2
1310 changed files with 132250 additions and 0 deletions
@@ -0,0 +1,239 @@
+---
+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`。
@@ -0,0 +1,2 @@
+interface:
+  display_name: "UI Requirement Planner"
@@ -0,0 +1,141 @@
+# 规划模板
+
+当用户希望获得完整、可执行的前端实施方案时，使用本参考模板。
+
+## 默认输出模板
+
+### 需求摘要
+- 目标：
+- 核心用户：
+- 关键操作：
+- 约束条件：
+- 假设项：
+
+### 页面与组件架构
+- 路由/页面容器职责：
+- 组件树：
+- 展示型组件：
+- 业务组件：
+- 可复用候选模块：
+
+### 状态与数据流
+- 页面本地状态：
+- 派生状态：
+- 交互事件：
+- 异步流程：
+- 是否需要 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`，确保替换真实图前后布局不抖动
+````