每个单元生成Spec的文档
生成Spec文档的提示词模板
bash
好的,这个拆分方案我接受。
现在请为 homepage-hero 生成完整的Spec文档。
文档结构要求:
1. 模块边界(包含什么/不包含什么)
2. 核心场景(WHEN/THEN/AND格式,覆盖正常+异常路径)
3. 数据结构(组件Props定义、类型与约束)
4. 验收标准(ACCEPTANCE Checklist)
技术约束:
- React + Next.js App Router
- Tailwind CSS + shadcn/ui
- 响应式 (mobile-first)
- next/image图片优化
输出保存为 specs/homepage-hero.md提示词结果如下
文档信息
| 项目 | 内容 |
|---|---|
| 单元编号 | H-01 |
| Spec 版本 | V1.0 |
| 日期 | 2026-11-16 |
| 上游文档 | 《WanderChina首页开发单元拆分》V1.1、《WanderChina_MVP_P0模块规格说明》V1.2 |
| 技术栈 | React + Next.js App Router · Tailwind CSS + shadcn/ui · 响应式 mobile-first · next/image 图片优化 |
| 所属页面 | 首页 / 第一个区块 |
| 评审状态 | 待评审 |
0. 技术约束(实现基线,必须遵守)
| 约束 | 落地要求 |
|---|---|
| Next.js App Router | 本区块为服务端组件(Server Component)为主,仅搜索框交互部分用客户端组件(use client) |
| Tailwind CSS | 全部样式用 Tailwind 原子类;断点采用 mobile-first(base → sm → md → lg) |
| shadcn/ui | 搜索框输入用 shadcn/ui Input;提示用 Toast(sonner)或 Tooltip,不手写原生 alert |
| 响应式 mobile-first | 先写移动端样式,再用断点向上增强;不得出现横向滚动条 |
| next/image | 背景图必须用 next/image(fill + sizes + priority),禁止用 <img> 或 CSS background-image 加载主视觉 |
1. 模块边界
1.1 包含什么(In Scope)
| # | 能力 | 说明 |
|---|---|---|
| 1 | 主视觉背景图 | 品牌背景图,用 next/image 渲染并做响应式裁切与懒加载优化 |
| 2 | 品牌标语 | 英文主 + 中文对照,取自配置 slogan_en / slogan_zh |
| 3 | 副标题 | 英文主 + 中文对照,取自配置 subtitle_en / subtitle_zh |
| 4 | 搜索框 UI 骨架 | 只读输入框 + 占位提示;点击/聚焦弹出「即将开放」提示 |
| 5 | 响应式布局 | 移动端到桌面端的字号、间距、高度自适应 |
| 6 | 文案配置化 | 全部文案由配置注入,不硬编码在组件里 |
本期种子文案(英文主 + 中文对照,原创,已过合规检查):
| 字段 | 英文(主) | 中文(对照) |
|---|---|---|
| 标语 | China, without the guesswork. | 玩转中国,不必先当「中国通」。 |
| 副标题 | Curated guides, honest traveler posts, and an AI that speaks your language — from touchdown to departure. | 精选攻略、真实游记、随时可问的 AI 助手 —— 从落地到离开,一路有解。 |
1.2 不包含什么(Out of Scope)
| # | 明确不做 | 原因 |
|---|---|---|
| 1 | ❌ 真实搜索逻辑(查询、结果页、联想词) | 全站搜索列为 P1,本期仅占位 |
| 2 | ❌ 搜索接口调用 | 点击不发起任何网络请求 |
| 3 | ❌ AI 助手入口 | 属 H-05(顶部图标 + 悬浮按钮),不在本区块 |
| 4 | ❌ 城市入口 / 热门内容 | 属 H-03 / H-04 |
| 5 | ❌ 用户个性化内容 | 无登录态差异化 |
| 6 | ❌ 图片上传 / 运营后台 UI | 配置由 H-09 种子数据直接维护 |
| 7 | ❌ 视频 / 动效背景 | 本期静态图 |
边界提示:搜索框「占位」指 UI 可见但不可真正搜索;点击应给明确反馈(Toast),不得是死输入框或无响应。
2. 核心场景(WHEN / THEN / AND,覆盖正常 + 异常路径)
2.1 正常路径
| 编号 | 场景 |
|---|---|
| S-01 | 首屏正常渲染 — WHEN 用户打开首页 / THEN 系统展示背景图 + 英文标语 + 英文副标题 + 中文对照 + 搜索框 AND 内容取自当前启用的 home_hero_config 配置行 |
| S-02 | 搜索框占位反馈 — WHEN 用户点击或聚焦搜索框 THEN 系统弹出提示「Search is coming soon / 搜索功能即将开放」 AND 不发起任何网络请求、不跳转页面 |
| S-03 | 配置驱动文案 — WHEN 运营修改 slogan_en 并更新配置 THEN 前端在 5 分钟内展示新文案 AND 无需重新发版 |
| S-04 | 首屏性能 — WHEN 用户在 4G 网络下首次访问 THEN Hero 区块在 2 秒内可见(P75,LCP 目标) AND 背景图由 next/image 优化输出 WebP/AVIF 并按 sizes 加载合适尺寸 |
2.2 异常与边界路径
| 编号 | 场景 |
|---|---|
| S-05 | 背景图加载失败 — WHEN 背景图 URL 失效或加载报错 THEN 系统展示 CSS 渐变兜底背景 AND 标语/副标题/搜索框仍完整可读、不出现空白页 |
| S-06 | 配置缺失 — WHEN home_hero_config 无启用行或字段为空 THEN 系统使用组件内置默认文案(即本期种子文案)渲染 AND 记录一条 hero_config_missing 日志,页面不崩溃 |
| S-07 | 超长文案 — WHEN 配置的标语/副标题超出预设字符数(标语 >80、副标题 >200) THEN 系统进行响应式字号收缩 + 最多 2/3 行截断(line-clamp) AND 不溢出容器、不产生横向滚动 |
| S-08 | 慢网加载态 — WHEN 背景图尚未加载完成 THEN 系统先展示纯色/渐变占位 + 文案 AND 图片加载完成后平滑过渡,不出现布局跳动(CLS 可控) |
| S-09 | 多语言/特殊字符 — WHEN 文案含 emoji、中文标点、长英文单词 THEN 文本正确换行且无乱码 AND 编码为 UTF-8 |
| S-10 | 响应式边界 — WHEN 视口为 320px / 375px / 768px / 1440px THEN 标语为 1 行(移动端可 2 行)、副标题不遮挡搜索框 AND 各断点均无横向滚动、无文字截断错位 |
| S-11 | 键盘与读屏可达 — WHEN 用户用 Tab 键聚焦搜索框 THEN 焦点样式清晰可见 AND 读屏可朗读占位文案与「即将开放」提示(无障碍 accessible) |
| S-12 | 重复点击 — WHEN 用户连续多次点击搜索框 THEN 提示不重复堆叠(Toast 去重/节流) AND 无性能异常 |
3. 数据结构(组件 Props 定义、类型与约束)
3.1 配置数据来源
| 字段 | 类型 | 来源 | 约束 |
|---|---|---|---|
id | number | home_hero_config | 主键 |
bannerUrl | string | banner_url | 合法 URL;允许为空(空则用兜底渐变) |
sloganEn | string | slogan_en | 必填,≤80 字符 |
sloganZh | string | slogan_zh | 必填,≤80 字符 |
subtitleEn | string | subtitle_en | 必填,≤200 字符 |
subtitleZh | string | subtitle_zh | 必填,≤200 字符 |
status | 'ON' | 'OFF' | status | 仅 ON 生效 |
3.2 TypeScript Props 定义
ts
// types/hero.ts
export interface HeroConfig {
id: number;
bannerUrl: string | null; // 允许为空 → 兜底渐变
sloganEn: string;
sloganZh: string;
subtitleEn: string;
subtitleZh: string;
status: "ON" | "OFF";
}
// 组件对外 Props(服务端组件)
export interface HeroProps {
/** 配置数据;缺省时组件使用内置 DEFAULT_HERO_CONFIG */
config?: HeroConfig | null;
/** 是否首屏优先加载背景图,默认 true */
priority?: boolean;
/** 可选的额外类名,供 H-07 装配时调整间距 */
className?: string;
}3.3 组件拆分(App Router)
| 组件 | 类型 | 职责 |
|---|---|---|
Hero (components/hero/Hero.tsx) | Server Component | 读取配置、渲染背景图(next/image)+ 标语 + 副标题 + 组合子组件 |
SearchPlaceholder (components/hero/SearchPlaceholder.tsx) | Client Component("use client") | 只读搜索框,处理点击/聚焦 → Toast 提示;用 shadcn/ui Input + sonner toast |
HeroFallback | Server Component | 背景图失败/为空时的渐变兜底层 |
服务端/客户端边界:仅
SearchPlaceholder需要交互(useState/ 事件处理 / toast),标记"use client";其余保持服务端组件,减少客户端 JS。
3.4 常量与约束
ts
export const DEFAULT_HERO_CONFIG: Omit<HeroConfig, "id" | "status"> = {
bannerUrl: null,
sloganEn: "China, without the guesswork.",
sloganZh: "玩转中国,不必先当「中国通」。",
subtitleEn:
"Curated guides, honest traveler posts, and an AI that speaks your language — from touchdown to departure.",
subtitleZh:
"精选攻略、真实游记、随时可问的 AI 助手 —— 从落地到离开,一路有解。",
};
export const HERO_LIMITS = {
sloganMax: 80,
subtitleMax: 200,
toastMessage: "Search is coming soon / 搜索功能即将开放",
} as const;3.5 next/image 关键配置
| 属性 | 值 | 说明 |
|---|---|---|
fill | true | 背景图铺满容器,容器需 relative |
sizes | (max-width: 640px) 100vw, (max-width: 1024px) 100vw, 50vw | mobile-first,按视口加载合适尺寸 |
priority | ={priority}(默认 true) | 首屏 LCP 优化 |
alt | WanderChina brand background | 无障碍 |
onError | 触发 HeroFallback | 加载失败兜底(客户端处理,见 2.2 S-05) |
若
bannerUrl为空,不渲染next/image,直接输出HeroFallback渐变层。
3.6 Tailwind 响应式要点(mobile-first)
| 元素 | 移动端(base) | sm/md 及以上 |
|---|---|---|
| Hero 容器高度 | min-h-[60svh] | md:min-h-[72svh] |
| 标语字号 | text-3xl | md:text-5xl lg:text-6xl |
| 副标题字号 | text-sm | md:text-lg |
| 中文对照 | text-xs opacity-80 | md:text-sm |
| 内容宽度 | max-w-xl | md:max-w-3xl |
| 搜索框宽度 | w-full | md:max-w-lg |
| 布局 | 垂直堆叠 | 垂直堆叠(保持),字号/间距放大 |
4. 验收标准(ACCEPTANCE Checklist)
4.1 功能验收
- [ ] AC-01 首页
/加载后 Hero 区展示背景图 + 英文标语 + 英文副标题 + 中文对照 + 搜索框,内容与启用配置一致 - [ ] AC-02 标语/副标题为「英文主 + 中文对照」双层展示,文案与 §1.1 种子文案一致(初始状态)
- [ ] AC-03 点击/聚焦搜索框弹出「Search is coming soon / 搜索功能即将开放」提示,且 Network 面板无请求、URL 不变
- [ ] AC-04 修改配置后 5 分钟内前端文案更新,无需重新构建发版
4.2 异常与健壮性验收
- [ ] AC-05 将
bannerUrl置空或改为失效 URL:显示 CSS 渐变兜底,文案与搜索框仍完整可读,无报错 - [ ] AC-06 删除所有配置行或字段留空:组件使用内置默认文案渲染,不崩溃,控制台有
hero_config_missing日志 - [ ] AC-07 配置超长文案(标语 100 字 / 副标题 250 字):字号收缩并截断,容器不溢出、页面无横向滚动
- [ ] AC-08 弱网(Network 设为 Slow 3G):图片加载期间先显示占位与文案,图片到位后过渡平滑,无明显布局跳动
4.3 技术约束验收
- [ ] AC-09 背景图使用
next/image(fill+sizes+priority),构建产物中无主视觉的<img>或 CSSbackground-image加载 - [ ] AC-10 组件遵循 App Router 规范:
Hero为 Server Component,仅SearchPlaceholder使用"use client" - [ ] AC-11 样式全部使用 Tailwind 原子类;搜索框使用 shadcn/ui
Input,提示使用 sonnerToast/Tooltip - [ ] AC-12 采用 mobile-first 断点;在 320 / 375 / 768 / 1440px 四档视口下均无横向滚动、无文字错位
4.4 无障碍与质量验收
- [ ] AC-13 Tab 键可聚焦搜索框,焦点样式可见;读屏可朗读占位文案与提示(aria 属性完整)
- [ ] AC-14 连续点击搜索框 5 次,Toast 不堆叠、无性能异常
- [ ] AC-15 组件单元测试覆盖:正常渲染 / 搜索提示 / 空配置兜底 / 图片失败兜底 / 超长文案 / 四档视口快照
- [ ] AC-16 Lighthouse 无障碍 ≥90,Hero 区块对 LCP 无负贡献(图片
priority生效)
5. 依赖与交付
| 项目 | 内容 |
|---|---|
| 上游依赖 | H-09 配置与种子数据(home_hero_config);H-08 可选接口 /api/home/hero |
| 下游被依赖 | H-07 页面装配(作为首页第一个区块) |
| 交付物 | Hero.tsx(Server)、SearchPlaceholder.tsx(Client)、HeroFallback.tsx、types/hero.ts、单元测试、Storybook 故事(可选) |
| 待确认 | ① 背景图素材来源与授权(建议自绘渐变或已授权图片,避免侵权);② Hero 搜索框是否长期占位(C2) |
本 Spec 为产品设计参考,具体实施请结合公司合规与法务要求确认。示例文案为原创,示例数据均为虚构。
审核Spec文档
- 提示词
bash
请审查生成的spec文档,重点找出以下问题:
1、安全风险-越权、信息泄漏、未做限流的接口
2、数据问题-字段类型/长度/索引是否合理
3、逻辑漏洞-有没有"没说清楚"的灰色地带
4、异常路径-空值、超长、并发:重复点击有没有覆盖
5、验收标准-验收是否可量化、可测试
每条问题给出:在文档哪一行、有什么问题、怎么改修改完毕后
如果这个spec不在change目录下面也没有tasks.md文件
- 利用 /opsx:propose 这个技能 读取这个spec文档 生成change和tasks.md
如果这个spec文档已经在change目录下面有tasks.md文件
- 利用 /opsx:apply 这个技能 按 tasks.md 逐项写代码